W
Wrkr

Security Team Org Inventory and Compliance Handoff

Security Team Org Inventory and Compliance Handoff

Use this workflow when platform or security teams need the recommended minimum-now Wrkr path: deterministic org posture first, then compliance-ready evidence that can be verified offline.

Exact commands

Hosted prerequisites for this path:

  • pass --github-api https://api.github.com (or set WRKR_GITHUB_API_BASE)
  • export WRKR_GITHUB_TOKEN="$(gh auth token)" once for the engagement; assessment org scans require authenticated coverage by default
  • token resolution order is --github-token, config auth.scan.token, WRKR_GITHUB_TOKEN, then GITHUB_TOKEN
  • fine-grained PAT guidance: select only the target repositories and grant read-only repository metadata plus read-only repository contents
  • connector endpoints: GET /orgs/{org}/repos, GET /repos/{owner}/{repo}, sparse tree/blob reads, and a bounded tarball fetch for explicit broad-source scans
  • if hosted prerequisites are not ready yet, start with wrkr scan --path ./your-repo --state ./.wrkr/last-scan.json --report-md --report-md-path ./.tmp/scan-summary.md or wrkr scan --my-setup --state ./.wrkr/last-scan.json first and return to this flow when GitHub access is configured; --path scans the selected directory itself when it is the repo root and uses bundle roots like ./scenarios/wrkr/scan-mixed-org/repos when you want a deterministic repo-set
export WRKR_GITHUB_TOKEN="$(gh auth token)"
wrkr init --non-interactive --org acme --github-api https://api.github.com
wrkr scan --config ~/.wrkr/config.json --state ./.wrkr/last-scan.json --timeout 30m --profile assessment --report-md --report-md-path ./.wrkr/scan-summary.md --sarif --sarif-path ./.wrkr/wrkr.sarif
wrkr report --state ./.wrkr/last-scan.json --template agent-action-bom --md --md-path ./.wrkr/agent-action-bom.md --evidence-json --evidence-json-path ./.wrkr/agent-action-bom-evidence.json
wrkr report --state ./.wrkr/last-scan.json --template ciso --md --md-path ./.wrkr/ciso.md --pdf --pdf-path ./.wrkr/ciso.pdf --evidence-json --evidence-json-path ./.wrkr/report-evidence.json --csv-backlog --csv-backlog-path ./.wrkr/control-backlog.csv
wrkr report --state ./.wrkr/last-scan.json --template action-contract-packet --contract-id pac-0123456789abcdef --share-profile customer-redacted --md --md-path ./.wrkr/action-contract-packet.md --json
wrkr evidence --frameworks eu-ai-act,soc2,pci-dss --state ./.wrkr/last-scan.json --output ./wrkr-evidence
wrkr verify --chain --state ./.wrkr/last-scan.json

wrkr evidence now requires the saved proof chain to be intact before it stages or publishes a bundle, and wrkr verify --chain --json remains the explicit operator/CI integrity gate. wrkr init can now persist the hosted GitHub API base together with the default org target, so the follow-on wrkr scan --config ... path stays copy-pasteable without repeating --github-api on every run.

If resumability is required, start the original scan with --source-retention retain_for_resume. Only then does an interrupted run retain materialized roots and emit a valid --resume hint:

wrkr scan --config ~/.wrkr/config.json --state ./.wrkr/last-scan.json --source-retention retain_for_resume --resume --json --json-path ./.wrkr/scan.json

The default ephemeral mode removes materialized roots after interruption and must be rerun from the beginning.

Interpretation notes:

  • --progress auto keeps --json stdout clean and preserves structured stderr progress by default; use --progress events to keep explicit event lines, --progress none for CI-stable stderr, or --quiet to suppress progress output entirely
  • retry, cooldown, resume, per-repo materialization completion, local repo discovery, detector lifecycle, heartbeat, scan phase, and final footer progress lines are additive stderr-only operator UX in --json mode
  • partial_result, source_errors, or source_degraded means the org posture is incomplete and should be rerun before downstream campaign-style aggregation, even when wrkr scan status --json reports status=completed
  • org-checkpoints/ is resumability metadata beside the scan state, not a proof artifact
  • --resume revalidates checkpoint files and reused materialized repo roots before detector execution, so symlink-swapped resume state is blocked as unsafe
  • wrkr scan status --state ./.wrkr/last-scan.json --json now surfaces additive progress_percent, progress_message, last_progress_at, phase_progress, repo_progress, and detector_progress fields during active, interrupted, or completed-partial runs
  • repo_progress.completed counts terminal source-acquisition results, repo_progress.succeeded isolates successful materializations, and repo_progress.pending stays total - completed so failed repos are counted once

Optional deeper triage after the saved state exists:

wrkr mcp-list --state ./.wrkr/last-scan.json --gait-trust ~/.gait/trust-registry.yaml --json
wrkr report --top 5 --template appsec --json

Expected JSON keys

  • scan (hosted org mode): status, target, findings, ranked_findings, top_findings, inventory, repo_exposure_summaries, profile, posture_score
    • inventory.security_visibility_summary gives you the additive unknown_to_security counts and reference basis for that run
    • agent_privilege_map[*] is instance-scoped and includes agent_instance_id, write_capable, and security_visibility_status
  • evidence: status, output_dir, frameworks, manifest_path, chain_path, framework_coverage
  • evidence.coverage_note: additive interpretation for low/zero first-run coverage; treat it as an evidence-gap signal, not unsupported framework parsing
  • evidence.next_steps: additive machine-readable handoff guidance for verify/report sequencing and generated artifact-field review
  • verify: status, chain
  • mcp-list: status, generated_at, rows, optional warnings
  • report: status, generated_at, additive next_steps, additive agent_action_bom, additive runtime_evidence when a managed runtime evidence sidecar exists, top_findings, total_tools, summary, optional artifact_paths
    • agent_action_bom.items[*]: buyer-facing control_state, risk_zone, review_burden, path-level gait_coverage, workflow-token-vs-PAT credential posture, and deterministic introduced_by provenance when repo-local provenance metadata is present
  • action-contract-packet: direct packet-schema v1 JSON with identity, path, authority_requirements, credential_posture, readiness_checks, effects, confirmation_requirement, approval_requirement, compensation_requirement, evidence_gaps, lifecycle_observations, reachability, and next_step

How to frame the results

  • scan and mcp-list answer inventory, privilege, and trust-overlay questions.
  • scan --profile assessment gives the bounded customer-readout view of risky write paths first while leaving raw findings and proof artifacts intact.
  • scan is the place to count unknown-to-security write-capable paths; use inventory.security_visibility_summary.unknown_to_security_write_capable_agents only when inventory.security_visibility_summary.reference_basis is present for that run.
  • report --template agent-action-bom is the canonical joined operator artifact for risky action-path inventory, graph refs, proof refs, runtime evidence correlation, and next-action priority.
  • scripts/run_agent_action_bom_demo.sh after provides a deterministic demo handoff that reproduces the same BOM plus runtime evidence bundle path locally.
  • report can also emit customer-ready CISO/AppSec/platform/audit/customer-draft artifacts led by the control backlog.
  • report --template action-contract-packet --contract-id <id> emits one opt-in buyer packet from the same normalized portable contract artifact. The selector is explicit, weak evidence remains visible, and static reachability is not upgraded to observed execution.
  • report is a saved-state renderer for static posture and offline proof artifacts; it is not a live observation surface.
  • report.next_steps and evidence.next_steps are additive machine-readable sequencing hints for the operator-to-auditor handoff path; use them when you want automation or agents to follow the same artifact workflow the docs describe, using the referenced artifact fields in the same payload.
  • evidence packages the saved posture into portable proof artifacts only when the saved proof chain is intact, and verify remains the explicit machine gate for proof integrity.
  • coverage_note is the machine-readable companion to framework_coverage; use it when handing results to operators or downstream automation so sparse first-run evidence is framed as a remediation queue instead of a parser failure.

Operator-to-auditor handoff packet

Operator runs:

  • wrkr scan --config ~/.wrkr/config.json --state ./.wrkr/last-scan.json ... --json
  • wrkr report --state ./.wrkr/last-scan.json --template ciso --md --md-path ./.wrkr/ciso.md --pdf --pdf-path ./.wrkr/ciso.pdf --evidence-json --evidence-json-path ./.wrkr/report-evidence.json --csv-backlog --csv-backlog-path ./.wrkr/control-backlog.csv --json
  • wrkr report --state ./.wrkr/last-scan.json --template action-contract-packet --contract-id pac-0123456789abcdef --share-profile customer-redacted --md --md-path ./.wrkr/action-contract-packet.md --json
  • wrkr evidence --frameworks eu-ai-act,soc2,pci-dss --state ./.wrkr/last-scan.json --output ./wrkr-evidence --json
  • wrkr verify --chain --state ./.wrkr/last-scan.json --json

Buyer, GRC, or audit consumer reads:

  • ./.wrkr/ciso.md or ./.wrkr/ciso.pdf for the narrative summary
  • ./.wrkr/report-evidence.json for machine-readable report evidence
  • ./.wrkr/control-backlog.csv for owner/SLA/closure tracking
  • ./.wrkr/action-contract-packet.md for one selected proposal's authority, readiness, effect, approval, compensation, and downstream-evidence review
  • ./wrkr-evidence/ for the portable bundle, manifest, framework mappings, and proof artifacts
  • the verify --chain --json result for explicit integrity confirmation

Use report.next_steps and evidence.next_steps when you want automation to follow this same packet flow without reconstructing the sequence from docs.

Scope boundary

Wrkr does not perform live MCP probing or package/server vulnerability assessment in this workflow. Use dedicated scanners such as Snyk for those surfaces. Gait interoperability is optional and provides control-layer context rather than a requirement to run Wrkr.

Canonical state, baseline, manifest, and proof-chain paths are documented in docs/state_lifecycle.md.

First engagement runbook

export WRKR_GITHUB_TOKEN="$(gh auth token)"
wrkr scan --org acme --profile assessment --state ./.wrkr/acme.json --progress events --json-path ./.wrkr/acme-summary.json
wrkr scan --path ./customer-repos --profile assessment --execution-topology ./execution-topology.yaml --state ./.wrkr/deep.json
wrkr ingest --state ./.wrkr/deep.json --input ./runtime-evidence.json --json
wrkr report --state ./.wrkr/deep.json --template design-partner-summary --share-profile internal --md --md-path ./.wrkr/internal.md
wrkr report --state ./.wrkr/deep.json --template design-partner-summary --share-profile customer-redacted --md --md-path ./.wrkr/customer.md
wrkr verify --chain --state ./.wrkr/deep.json --json

Start with sparse authenticated org acquisition. Use maintained local clones for deep analysis when shared libraries, generated specifications, submodules, or broad source are required. Do not use stale developer worktrees as customer evidence. Ask the customer only for mappings and external facts Wrkr cannot observe: shared-library registration, credential activity/lifetime, actual environments/targets, enforced provider controls, and runtime outcomes.