DEV Community

Shizuku
Shizuku

Posted on

What a “Development Session Proof” Workflow Looks Like with SessionAttested

#security #devops #docker #attestation

This article is a hands-on / operational follow-up to my earlier write-up about SessionAttested.

Instead of focusing on architecture or implementation internals, this one focuses on:

  • how SessionAttested fits into a real development workflow
  • how policy refinement actually works in practice
  • what audit results look like in the built-in WebUI

The example used here is a real PoC workspace: attested_poc/.

In that PoC, I compare two cases under a policy that forbids VS Code (server/node executables):

  • a session without VS Code usage (PASS)
  • a session with VS Code usage (FAIL)

If you want to jump straight to the repository:

What This Article Tries to Show

SessionAttested is not only about “detecting forbidden tools.”

What becomes more interesting in practice is that it gives you a repeatable workflow for:

  • auditing development work in session-sized units
  • binding sessions to commits
  • evaluating them against a policy
  • producing signed outputs
  • reviewing the results later (including cumulative observations across sessions)

That is the angle I want to show here.

The PoC Scenario (VS Code Forbidden Policy)

In attested_poc/, I use a policy that treats VS Code-related executables (specifically VS Code Server / node) as forbidden.

This makes it easy to compare two sessions:

  • PASS case: development without VS Code
  • FAIL case: development with VS Code (Remote SSH workflow)

This is useful because it demonstrates both:

  • the policy verdict (PASS/FAIL)
  • the audit evidence (what was observed in exec / writer)

A Real Workflow (How It Feels to Use)

The workflow I ended up using repeatedly looks like this:

  1. attested workspace init (auditor)
  2. attested start (auditor)
  3. Work in the dev container + attested git commit (auditee)
  4. attested stop (auditor)
  5. attested attest / attested verify (auditor)
  6. Push (auditor or auditee, depending on policy)
  7. Repeat steps 2–6 for the next session

The important point is:

  • workspace/container lifecycle is separate from
  • session lifecycle

So the container can be reused across sessions, while audit boundaries remain clear.

1) Workspace Initialization (attested workspace init)

You start from the project directory and run:

attested workspace init
Enter fullscreen mode Exit fullscreen mode

Current behavior (interactive-friendly):

  • asks for workspace-id
  • uses current working directory as default workspace path
  • asks whether to build or pull the container image (default: build)
  • optionally mounts a host SSH key for Git push from the container
  • can capture GitHub repo / git user.name / git user.email

This does more than “register a workspace”:

  • creates SessionAttested scaffolding (attest/attested.yaml, attest/Dockerfile, attest/policy.yaml)
  • prepares .attest_run/
  • creates/registers the dev container (left stopped)

That means the workspace becomes immediately usable as a SessionAttested-enabled dev environment.

[IMAGE MARKER] workspace init prompt flow / generated files (optional screenshot)

2) Start a Session (attested start)

To begin audited work:

attested start
Enter fullscreen mode Exit fullscreen mode

What happens:

  • the dev container starts (or is reused if already created)
  • the collector starts automatically (if configured)
  • a new session_id is issued
  • .attest_run/last_session_id is updated (used by no-argument flows)

This is the point where SessionAttested begins collecting:

  • exec events
  • /workspace write events

3) Work Inside the Dev Container + Commit (attested git commit)

Inside the container, the workflow feels close to normal development:

  • connect via SSH / VS Code Remote SSH / docker exec
  • edit code
  • run commands
  • commit changes

The key difference is that session-linked commits should use:

cd /workspace
attested git add -A
attested git commit -m "first commit"
Enter fullscreen mode Exit fullscreen mode

This preserves normal Git behavior and records session/commit linkage:

  • commit_binding.json (latest)
  • commit_bindings.jsonl (append-only history for multiple commits in one session)

This becomes part of the later attestation and verification flow.

4) Stop the Session (attested stop)

When work is done:

attested stop
Enter fullscreen mode Exit fullscreen mode

This finalizes the collector and writes aggregated outputs for that session:

  • audit_summary.json
  • event_root.json

Conceptually, this is the moment where “what happened in this dev session” becomes a closed, reviewable unit.

5) Attest + Verify (attested attest / attested verify)

Next, the auditor evaluates and verifies the session:

attested attest
attested verify --write-result
Enter fullscreen mode Exit fullscreen mode

This produces / updates:

  • .attest_run/attestations/latest/attestation.json
  • .attest_run/attestations/latest/attestation.sig
  • .attest_run/attestations/latest/attestation.pub
  • ATTESTED
  • ATTESTED_SUMMARY
  • ATTESTED_POLICY_LAST
  • ATTESTED_WORKSPACE_OBSERVED

Two outputs are especially useful in day-to-day use:

ATTESTED_SUMMARY

Per-session verification results (append-only history):

  • pass/fail
  • reason
  • commit(s)
  • policy match status

ATTESTED_WORKSPACE_OBSERVED

Workspace-level cumulative observed identities across sessions:

  • what executables have been seen
  • what writer identities have been seen
  • unresolved counters

This is extremely useful when building or refining a policy over time.

6) How Policy Refinement Actually Works (attested policy candidates)

SessionAttested identifies tools by executable fingerprint (SHA256), not only by path strings.

That means a practical policy workflow is:

  1. observe what actually ran
  2. generate candidates
  3. review and refine
  4. apply policy
  5. run another session and evaluate

Generate a Candidate Policy 

attested policy candidates --include-exec
Enter fullscreen mode Exit fullscreen mode

This produces something like:

  • .attest_run/policy.<session_id>.candidate.yaml

The candidate includes observed identities as forbidden_exec / forbidden_writers candidates.

Review Before Applying

In practice, this review step matters a lot.

Things to check:

  • Is this identity really a prohibited tool?
  • Is it just a shell/helper process (bash, sh, node) delegated by another tool?
  • Is this a temporary install/setup tool that should not be in policy?

In my PoC, I used this process to define a policy that flags VS Code Server / node executables as forbidden.

[IMAGE MARKER] policy snippet (attest/policy.yaml) showing VS Code-related forbidden entries

7) Reviewing Results in the WebUI (attested webui)

This is the new part in v0.1.1 that made the workflow much easier to inspect.

attested webui
Enter fullscreen mode Exit fullscreen mode

It launches a local HTTPS WebUI (self-signed certificate), and renders the recorded audit/verification outputs.

Why This Matters

Before the WebUI, the workflow was already functional, but reviewing results meant opening several files manually:

  • ATTESTED_SUMMARY
  • audit_summary.json
  • attestation.json
  • ATTESTED_WORKSPACE_OBSERVED

The WebUI makes this much faster.

Session List (PASS/FAIL at a Glance)

The first thing I check is the session list (“See other sessions”):

  • session time window
  • session id
  • conclusion (PASS/FAIL)

session_list

This immediately tells you which sessions need attention.

PASS Case View

For PASS sessions, the useful checks are:

  • attestation/verification status
  • audit summary counts
  • executed/writer identities observed in that session

pass_summary

FAIL Case View (VS Code Forbidden)

For FAIL sessions, the WebUI makes it easier to answer:

  • Why did it fail? (reason code)
  • Which identities matched the policy?
  • Was it exec, writer, or both?

fail_summary

And with the detail view:

  • applied policy snapshot
  • conclusion details
  • workspace cumulative observed identities

fail_detail

This makes the result much easier to explain to humans compared to raw files alone.

Important Note About the WebUI

The WebUI is a viewer for recorded results, not a replacement for attest / verify.

  • machine decision: attest / verify
  • human review: attested webui

That split has worked well in practice.

8) Who Should Push? (Auditor vs Auditee)

One thing I liked in actual usage: Git push can be done by either side.

  • Auditee (inside container) pushes directly
  • Auditor (host side) pushes only after attest/verify passes

Both are valid. Which one you choose depends on policy.

Pattern A: Auditee Pushes

Good when:

  • speed matters
  • auditing is used as evidence/review, not a hard release gate

Pattern B: Auditor Pushes After Verify

Good when:

  • you want an explicit “verified before publication” workflow
  • the auditor controls what gets pushed/published

The attested_poc setup supports either pattern.

9) What I Learned from Using It in Actual Workflows

1. It standardizes the workflow nicely

The repeated flow:

  • workspace init
  • start
  • work + attested git commit
  • stop
  • attest / verify

creates clear audit boundaries without much extra mental load.

2. It is still useful even for solo development

Even when auditor = auditee, it remains valuable as a high-confidence process record:

  • what ran
  • what wrote
  • which session/commit it was tied to

And ATTESTED_WORKSPACE_OBSERVED is especially useful for post-hoc review and policy tuning.

3. It doesn’t get in the way too much

Since auditing runs on the host and development happens in a dev container:

  • the host stays cleaner
  • the dev environment remains flexible
  • IDE choice is not heavily constrained

This matters more than it sounds if you actually try to use a security/audit tool in daily development.

10) Closing Thoughts

Using attested_poc as a concrete example made one thing clear to me:

SessionAttested is more useful when seen as a development-session proof workflow than as “just a detection tool.”

The combination that makes it work in practice is:

  • dev-container-scoped work
  • host-side observation of exec / writer
  • commit binding
  • policy evaluation
  • human review via WebUI

There is still room to improve (for example, persisting per-session attestation.json instead of only latest), but the workflow already feels usable enough to evaluate in real development.

References

Top comments (0)