Skip to content

security-team.md

Latest commit

 

History

History
71 lines (52 loc) · 5.51 KB

security-team.md

File metadata and controls

71 lines (52 loc) · 5.51 KB

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)
  • provide a GitHub token for private repos or to avoid public API rate limits
  • 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}, GET /repos/{owner}/{repo}/git/trees/{default_branch}?recursive=1, GET /repos/{owner}/{repo}/git/blobs/{sha}
  • if hosted prerequisites are not ready yet, start with wrkr scan --path ./your-repo --json or wrkr scan --my-setup --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
wrkr init --non-interactive --org acme --github-api https://api.github.com --json
wrkr scan --config ~/.wrkr/config.json --state ./.wrkr/last-scan.json --timeout 30m --profile assessment --json --json-path ./.wrkr/scan.json --report-md --report-md-path ./.wrkr/scan-summary.md --sarif --sarif-path ./.wrkr/wrkr.sarif
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

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 a hosted org scan is interrupted, rerun the same target with --resume to reuse checkpointed materialization state under the scan-state directory:

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

Interpretation notes:

  • retry, cooldown, resume, per-repo materialization completion, local repo discovery, scan phase, and completion 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
  • 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

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 --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
  • verify: status, chain
  • mcp-list: status, generated_at, rows, optional warnings
  • report: status, generated_at, top_findings, total_tools, summary

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 gives the ranked operator summary for triage.
  • report is a saved-state renderer for static posture and offline proof artifacts; it is not a live observation surface.
  • 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.

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.