SCN-010 inventory: shuffle-backend container (steady-state asset spec)

[Brad-Edwards]

ACES Methodology And Capture Tooling

Before starting inventory or encoding work on this issue, use the ACES asset inventory methodology and capture tooling:

• Methodology: https://github.com/Brad-Edwards/aces/blob/dev/docs/aces/inventory/asset-inventory-methodology.md
• Assurance report: https://github.com/Brad-Edwards/aces/blob/dev/docs/aces/inventory/methodology-assurance-report.md
• Codex capture skill: https://github.com/Brad-Edwards/aces/tree/dev/.codex-skills/aces-asset-inventory-capture
• Claude capture skill: https://github.com/Brad-Edwards/aces/tree/dev/.claude/skills/aces-asset-inventory-capture
• Container capture template: https://github.com/Brad-Edwards/aces/blob/dev/.codex-skills/aces-asset-inventory-capture/scripts/capture-container-evidence-template.sh
• Syft normalizer: https://github.com/Brad-Edwards/aces/blob/dev/.codex-skills/aces-asset-inventory-capture/scripts/normalize-syft-cyclonedx.jq

Summary

Apply the ACES asset-inventorying methodology to the shuffle-backend container as
realized in a fresh aptl lab start, capture the inventory at experiment
grade, and encode every observable fact directly in scenarios/techvault.sdl.yaml,
with referenced source packages and supporting artifacts used only as
evidence/provenance, not as substitutes for SDL facts.

Snapshot point: steady state after aptl lab start has fully
completed and the container has reached its operational state. The target
is the complete participant/agent-observable steady-state spec for that
moment. Time dynamics and attack-induced changes are separate work, but
any fact observable at the snapshot point is in scope and must be encoded
or blocked by an ACES expressivity issue.

Identifying information

• Container (docker-compose service): shuffle-backend
• Image source: ghcr.io/shuffle/shuffle-backend:latest (upstream image)
• Compose profile: soc
• Family: defensive-soc-app
• Parent tracker: SCN-010: ACES TechVault cutover issue series and validation gates #317
• Requirement: SCN-010
• Depends on: ACES methodology issue Methodology: reproducible deep asset inventorying for backend-realized scenarios (academically defensible) aces#353 (plus any
  other in-flight gap issues this asset surfaces during inventory)

Scope

Apply every dimension named by the ACES asset-inventorying methodology
(see Brad-Edwards/aces#353). At minimum:

• Image identity: base image registry + digest, all parent layers,
  build args used at build time.
• Build recipe: Dockerfile (or absence thereof for upstream images),
  every COPY / RUN / ARG / ENV line with the inputs each consumed.
• Package manifest at build time: dpkg -l / rpm -qa /
  pip freeze / npm ls / language-specific lockfile snapshot.
• Patch state: CVE inventory at snapshot time per the methodology's
  cited approach (Trivy / Grype / equivalent), with severity counts and
  per-vuln IDs.
• First-boot / provisioning state: every script that runs at build
  or first-start (e.g. containers/shuffle-backend/*.sh for custom builds),
  with inputs and the resulting on-disk state.
• Runtime configuration: env vars (declared in compose + resolved
  values, redacted per ADR-029 where they're operator secrets), exposed
  ports, capabilities, mounted volumes (bind + named), network
  attachments, healthcheck command + interval + retries + start_period,
  restart policy, ulimits.
• Filesystem inventory at steady state: all participant/agent-
  observable steady-state filesystem paths, file metadata, permissions,
  ownership, and checksums/content references. Do not exclude logs,
  caches, generated files, or runtime-created state solely because they
  are transient; if their values are unstable, record the stability
  limits and either encode the observable shape in SDL or file/link an
  ACES expressivity blocker. Include configuration files, fixture
  content, certificates, pre-seeded data, agent installers, application
  source, templates, static assets, and generated startup artifacts
  visible from inside the range.
• Identity surfaces local to this host: local users + UID/GID,
  shells, home dirs, sudo entries, any service accounts owned by this
  container (AD users live in ad's inventory, not in their consumer's).
• Service surfaces: every open port + protocol + bound interface;
  the application or daemon listening; readiness criteria.
• Vulnerability inventory (target hosts only): declared scenario
  weaknesses (the SDL vulnerabilities entries this host carries),
  cross-checked against the realized form (CVE state).
• Relationships originating at this host: which services it
  connects to (with protocol + port + auth method); which observers /
  sidecars / agents ingest from it; trust relationships it participates
  in.
• Authored-vs-realized split: explicit per field. Which dimensions
  are authored intent (encoded in SDL), which are realized form
  (covered by ACES EXP-722 disclosure surfaces / equivalent), which
  are provenance (covered by ACES EXP-720 / equivalent). Cite the
  methodology section that governs each.

The inventory is a steady-state snapshot. Time dynamics and attack-
induced transitions may be separate work, but any state observable at the
snapshot point, including logs, caches, generated files, volume contents,
and ephemeral runtime telemetry present at capture time, must be encoded
or blocked by an ACES expressivity issue rather than silently excluded.

Acceptance

• Inventory captured under docs/aces/inventory/shuffle-backend/ as a frozen
  artifact, following the methodology's named artifact shape. Every
  claim cites the source it was observed at (provisioner line,
  docker inspect output, dpkg -l line, file checksum, etc.).
  Reviewer can re-run the cited commands and reproduce each claim.
• All inventory surfaces that ACES can express today are encoded directly
  in scenarios/techvault.sdl.yaml. Referenced source packages,
  Dockerfiles, Compose services, checksums, evidence bundles, and mapping
  notes are proof inputs only; they do not substitute for SDL expression.
  Any observable detail that ACES cannot express must be linked to a
  blocking ACES expressivity issue.
• ACES expressivity gaps: every surface the inventory captured but
  ACES grammar cannot represent today has a corresponding new issue
  filed against Brad-Edwards/aces, with the issue URL linked from
  this issue's body. Each gap issue must cite this inventory as its
  motivating consumer.
• APTL runtime consumption is outside this inventory issue; do not file or use APTL gaps as a substitute for ACES SDL expression.
• pytest tests/ -q -k "not integration" passes.
• pre-commit run --all-files passes.
• Traceability link added in Ground Control: SCN-010 ←
  docs/aces/inventory/shuffle-backend/.
• The SCN-010 parity inventory at docs/aces/parity-inventory.yaml is
  updated where rows for this asset move between categories (e.g.
  aces_schema_profile_gap → aces_sdl once a corresponding ACES
  upstream issue lands; aptl_backend_responsibility rows updated to
  cite the realized form).

Honesty / claims framing

• The inventory establishes a spec for this asset at steady state,
  cited against observed reality at a single point in time.
• The inventory does NOT itself prove byte-identical re-buildability;
  that's a separate equivalence-checker concern. It does provide the
  ground truth a future equivalence checker compares against.
• The inventory does not by itself cover behavior over time, attack-
  induced state transitions, or later operator-driven runtime changes,
  but any state present at the steady-state snapshot is in scope. If a
  dynamic surface must be excluded from this issue, link the issue that
  owns it and record the limit.
• Any surface where the inventory could not be fully resolved (closed
  upstream source, opaque image, undocumented behavior) must be flagged
  in the inventory artifact as a known limit, not silently elided.

Migration note

This issue carries the shuffle-backend per-asset inventory work after APTL #353 was corrected to be methodology/tooling only. The methodology/tooling support landed in PR #359; use docs/aces/inventory/asset-inventory-methodology.md, docs/aces/inventory/methodology-assurance-report.md, and aptl aces-inventory validate/gaps/schema when implementing this asset inventory.

Stop Condition

This issue has two goals:

1. Move TechVault closer to a complete ACES spec by encoding the catalogued, in-scope observable facts for this asset/composition in scenarios/techvault.sdl.yaml.
2. Identify ACES SDL expressivity gaps. If ACES cannot express a catalogued in-scope fact, file/link a blocking Brad-Edwards/aces issue and leave this issue open until ACES lands and the SDL is updated.

Use #330 as the depth bar: configs, versions, packages, files, permissions, users, services, relationships, vulnerabilities, runtime artifacts, checksums/provenance, and explicit claim boundaries belong in scope when they are observable for this asset/composition.

Evidence, Docker/Compose files, source trees, checksums, logs, screenshots, inventories, and mapping ledgers are proof inputs only. They do not substitute for SDL expression. APTL runtime consumption is separate and never justifies omitting SDL content.

Do not close this issue on representative subsets, relevance judgments, APTL support gaps, or evidence-only capture. Close it only when every catalogued in-scope observable is either encoded in SDL or blocked by a linked ACES expressivity issue.

Completion checklist:

• Catalogued the in-scope participant/agent-observable facts for this surface.
• Encoded every ACES-expressible catalogued fact in scenarios/techvault.sdl.yaml.
• Filed and linked ACES blocker issue(s) for every catalogued fact ACES cannot express.
• Verified no catalogued fact remains evidence-only without SDL encoding or an ACES blocker.
• Updated the parity inventory / mapping ledger for every encoded or blocked fact.
• Recorded claim boundaries, such as snapshot-only capture, no full root filesystem enumeration, no byte-identical rebuild proof, or no time-dynamic behavior, when this issue does not capture those surfaces.

[Brad-Edwards]

🛠️ Picked up by /implement — driver Claude Code, branch 360-shuffle-backend-inv, 2026-06-05T05:49:12Z.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #360). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

[Brad-Edwards]

gc workflow phase recorded: plan (issue #360). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

Implementation plan — SCN-010 shuffle-backend inventory (completion grade)

Base: origin/dev (branch 360-shuffle-backend-inv). Requirement: SCN-010 (stays ACTIVE — umbrella requirement; this issue covers one asset). Depth bar: #330 / the merged misp inventory.

Decision: non-destructive capture from the running lab

The lab is up (aptl-shuffle-backend healthy, 12 days). Following the merged misp inventory precedent (and operator direction), this capture is non-destructive — it observes the already-running lab and does not run aptl lab stop -v && aptl lab start. The clean-reset / byte-identical-rebuild limit is recorded explicitly in capture-limits.txt + README. The existing bundle is the #353 methodology smoke pass; this issue upgrades it to an experiment-grade SCN-010 inventory.

1. Re-capture experiment-grade evidence

docs/aces/inventory/shuffle-backend/capture-evidence.sh (committed, re-runnable, digest-pinned tools) refreshes the bundle to misp parity:

• Image identity/history/layers, buildx + SLSA attestation manifests, compose-service slice (redacted env).
• docker inspect container/image, network, volume, top, logs.
• Alpine apk packages; Go dependency manifests (go.mod/go.sum; Go module table sourced from the SBOM since no Go toolchain ships in the image).
• Filesystem tree + checksums (compressed) over /app /app_gen /app_sdk /shuffle-database /etc /run.
• Runtime baseline: os-release, id, PID-1 capabilities/NoNewPrivs, env, netstat listeners + established, mounts, getent users/groups, process tree, binary info.
• Shuffle SOAR app-state via the live backend API (:5001) + OpenSearch _cat/indices and _search: 1 org, 1 admin user, 8 activated workflow-apps, 313-app catalog, workflow-execution counts — apikey/password/session fields redacted.
• Participant-vantage discovery from shuffle-orborus and kali.
• Trivy SBOM + vuln list/counts; Syft SBOM (normalized); osquery suite (processes, listening_ports, docker_containers/images; apt/installed_applications/programs recorded unavailable for Alpine/Linux image).
• capture-limits.txt, evidence-sha256sums.txt.

2. Encode every ACES-expressible fact in scenarios/techvault/nodes/shuffle-backend.sdl.yaml

Fill the currently-empty/null surfaces to misp depth: runtime.filesystem_inventory (load-bearing participant-visible paths with mode/owner/stability/sensitivity), service_listeners (in-container listening sockets), local_identity (users/groups), identity_authorities (Shuffle org + admin user + API-key metadata, redacted), platform_applications (Shuffle SOAR: org/workflow/app/execution state), applications (backend HTTP API surface on 5001), software_components (Go modules from SBOM), health (compose declares none — encode the observed absence with provenance), enriched image layers. Refresh packages/vulns/process/env from the new capture.

3. Relationships (scenarios/techvault/sections/relationships.sdl.yaml)

Encode relationships involving this host: shuffle-backend → shuffle-opensearch (datastore, HTTPS :9200, basic auth), inbound shuffle-frontend → shuffle-backend (nginx proxy) and shuffle-orborus → shuffle-backend (worker orchestration, HTTP :5001), and the docker.sock control surface. shuffle-opensearch/orborus/frontend are not yet TechVault nodes — model targets at the granularity ACES supports today; any unrepresentable edge becomes an ACES gap issue.

4. Docs, parity, test

• Rewrite README.md from smoke-test framing to a completion-grade SCN-010 inventory (encoded result, evidence highlights, limits, repro commands).
• Expand mapping-ledger.yaml to misp depth: every captured fact → ACES disposition (encoded/blocked), correspondence checks, limits.
• Update docs/aces/parity-inventory.yaml shuffle rows to cite the realized form.
• Add tests/test_shuffle_backend_inventory.py paralleling test_misp_inventory.py (ledger validates w/o gaps, evidence present + sha256-consistent, ledger references every evidence file, no raw secrets committed, runtime counts/caveats, SDL encodes the captured surfaces, capture script pins toolchain). Changelog fragment only if app-source changes (docs/SDL/tests are docs-class — likely none).

5. ACES expressivity gaps

For every catalogued in-scope fact ACES grammar cannot express today, file a Brad-Edwards/aces issue citing this inventory as the motivating consumer and link it from this issue body. If the current ACES runtime fields cover everything (preflight's expectation), record that blocked=0 explicitly.

6. Validate + reconcile (Phase B–D)

aptl aces-inventory validate/gaps (expect blocked=0 triage=0), the ACES SDL compile path (aces_sdl.parse_sdl_file + compiler), pytest -k "not integration", pre-commit run --all-files. Then completion gate, codex + test-quality review, commit, push, PR, CI, SonarCloud, and Ground Control reconciliation: add the SCN-010 ← docs/aces/inventory/shuffle-backend/ (and SDL) traceability link; preserve the existing issue→SCN-010 IMPLEMENTS link.

Guardrails (from architecture preflight)

ACES inventory + SDL authoring only — no APTL-local schema; evidence/ledger are proof inputs, facts live in the SDL; reuse the ledger CLI, parity gates, and ADR-029 redaction (aptl.utils.redaction); do not modify docker-compose.yml/startup to satisfy the inventory; new expressivity gaps become ACES issues, not APTL excuses.

Claim boundaries

Steady-state snapshot of the running lab at a single point in time. Not a clean-reset or byte-identical rebuild proof; not time-dynamic/attack-induced behavior. Scanner output is tool/DB-version-bound. Any surface that could not be resolved is flagged as a known limit, not silently elided.

[Brad-Edwards]

gc workflow phase recorded: traceability_reconciled (issue #360). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

• SCN-010: status=ACTIVE, IMPLEMENTS=57, TESTS=25

[Brad-Edwards]

gc_codex_review — cycle 1 of 1 (pre-push) on issue #360 (branch 360-shuffle-backend-inv)

Core review

Verdict: ship

The authoritative diff is empty, so there is no architectural shape, boundary contract, or cross-cutting helper usage to evaluate. This PR does not alter the repo's design vocabulary, tests, runtime behavior, or extension points, and it does not foreclose any obvious next variation. I would ship this as a no-op change.

No blocking findings.

Security review

Verdict: ship

There is no code shape to assess because the authoritative diff is empty. No security boundary, request path, repository access, secret handling, serialization surface, or supply-chain behavior is added or weakened by this PR. I would ship this from an application-security standpoint.

No blocking findings.

[Brad-Edwards]

gc_codex_review pre-push cycle 1 of 1 complete for issue #360 on branch '360-shuffle-backend-inv'. Posted by the MCP server to enforce the pre-push hard-cap-1 contract (issues #796, #804, #906). Do not edit or delete — used by the next gc_codex_review (uncommitted) invocation to count cycles.

[Brad-Edwards]

Review decision record — codex cycle 1 (issue #360)

Reviewer: codex
Cycle: 1

Architectural read:

Core reviewer: The authoritative diff is empty, so there is no architectural shape, boundary contract, or cross-cutting helper usage to evaluate. This PR does not alter the repo's design vocabulary, tests, runtime behavior, or extension points, and it does not foreclose any obvious next variation. I would ship this as a no-op change.

Security reviewer: There is no code shape to assess because the authoritative diff is empty. No security boundary, request path, repository access, secret handling, serialization surface, or supply-chain behavior is added or weakened by this PR. I would ship this from an application-security standpoint.

Blocking findings: 0 (clean run)

[Brad-Edwards]

gc_test_quality_review cycle 1 of 1 — issue #360

Reviewer: test-quality (claude-sonnet-4-6 via gc_test_quality_review)
Branch: 360-shuffle-backend-inv
Cycle: 1 / 1
Findings: 1

Finding 1 — [warning] tests/test_shuffle_backend_inventory.py:1

Problem: File is missing pytestmark = pytest.mark.integration. The tests read from committed evidence files, parse compressed JSON/YAML, call validate_mapping_ledger/gap_report, and invoke compile_runtime_model—all filesystem and library operations. The sibling file changed in this same diff (test_techvault_classification_audit.py) correctly carries the marker.
Why it matters: Any CI job or local run using -m 'not integration' includes this file in the unit pass. Those environments may not have the evidence bundle checked out, causing loud unrelated failures that mask real unit regressions. Conversely, a job that skips integration will silently skip the inventory checks.
Fix: Add pytestmark = pytest.mark.integration at module scope (after the imports, matching the placement in test_techvault_classification_audit.py:12).