security

Security Skill

Purpose: Run repeatable security checks across code, scripts, release gates, authorized binaries, and repo-managed prompt surfaces.

Use this skill for deterministic pre-merge/release validation, scheduled checks, authorized binary assurance, dependency risk, secrets, or offline prompt-surface redteam.

Critical Constraints

• Scan only repositories, binaries, and prompt surfaces the operator owns or is explicitly authorized to assess. Why: a security review does not grant access to third-party systems or proprietary material.
• Keep collection read-only by default; do not exfiltrate secrets, execute destructive payloads, or mutate policy/baselines to manufacture green. Why: the assessment must not become the incident or erase its evidence.
• Treat missing/error scanners as a coverage gap, never a clean finding; use --require-tools when complete tool coverage is required. Why: absent evidence is not evidence of absence.
• Use the current agent and local shell; do not start another runtime or orchestration substrate unless explicitly requested. Why: repository scanning is a bounded operation, not permission to fan out.
• WARN|FAIL|REFUTED -> AUTO-REDO: consult the pawl, reproduce and classify the finding, remediate only when authorized, then rerun the same gate. Why: a negative verdict is loop evidence, not a human andon by itself.
• BREAKER -> HOLD -> ONE-HELPER; HELPER-UNSTUCK -> AUTO-REDO. Hold promotion and use one bounded local-shell helper to inspect the scanner, artifact, or authorization boundary. Why: one recovery pass can distinguish tooling failure from a real security stop.
• HELPER-ESCALATE -> HUMAN; REFUSAL-LANE|EXPLICIT-JUDGMENT|EXHAUSTED-BUDGET -> HUMAN. Why: target authorization, risk acceptance, suppression/baseline judgment, or exhausted recovery requires accountable human ownership.

Security Surfaces

1. Repository gate: scripts/security-gate.sh composes available scanners for quick/full/release checks.
2. Composable suite: scripts/security_suite.py provides static, dynamic, contract, baseline, and policy primitives for authorized binaries.
3. Offline redteam: scripts/prompt_redteam.py checks repo-owned prompt and tool-control surfaces against the attack pack.

This is the canonical security runbook. Suite policy gating produces machine-consumable outputs, including policy/policy-verdict.json when a policy file is supplied.

Read the suite runbook before binary, policy, baseline, or redteam work. Use the OWASP checklist for code-level review.

Execution Workflow

1) Quick gate

Run:

scripts/security-gate.sh --mode quick

Checkpoint: preserve the exit code and verify the reported security-gate-summary.json exists and parses before triage.

2) Full or release gate

Run:

scripts/security-gate.sh --mode full

Add --require-tools when skipped scanners would invalidate the assurance claim. Checkpoint: do not authorize promotion until the full artifact passes the output validator and the process exits zero.

3) Scheduled gate

Scheduled automation runs the full gate against the intended branch and retains its artifact directory. A failing scheduled run creates actionable tracked work; AgentOps itself does not supply the scheduler.

4) Triage and re-run

1. Open the latest artifact and identify scanner, severity, file, and coverage gaps.
2. Reproduce the finding with the narrowest safe command.
3. For authorized remediation, fix critical/high findings; otherwise report them with owner and next action.
4. Re-run the same gate. Do not downgrade, suppress, or update a baseline merely to pass.

Output Specification

Artifact directory: repository gates write ${SECURITY_GATE_OUTPUT_DIR:-${TMPDIR:-/tmp}/agentops-security}/<run-id>/; composable-suite and redteam runs use their explicit --out-dir.

Filename convention: repository gates require security-gate-summary.json (and raw summary.json); suite runs require suite-summary.json; redteam runs require redteam/redteam-results.json.

Serialization/schema format: security-gate-summary.json is JSON with nonempty mode, run_id, output_dir, and gate_status, numeric missing_tool_count, boolean require_tools, and object toolchain.

Validator command: with OUT=<security-gate-run-dir>, run jq -e '(.mode|type)=="string" and (.mode|length)>0 and (.run_id|type)=="string" and (.run_id|length)>0 and (.output_dir|type)=="string" and (.output_dir|length)>0 and .gate_status=="PASS" and (.missing_tool_count|type)=="number" and (.require_tools|type)=="boolean" and (.toolchain|type)=="object"' "$OUT/security-gate-summary.json" >/dev/null.

Downstream handoff: pass the artifact path, command/exit code, mode, gate status, missing-tool coverage, ranked findings, authorization boundary, owner, and next action to validation/release; negative verdicts re-enter through the pawl.

Quality Checklist

• Target and authorization boundary are explicit; collection stayed within them.
• Scanner availability and skipped/error coverage are visible in the report.
• Findings include severity, location, reproducible evidence, and remediation/owner.
• Artifacts contain no newly exposed secrets or unredacted sensitive payloads.
• Required gate and output validator both pass before promotion is declared safe.
• Suppressions, policy changes, baselines, and risk acceptance require explicit judgment.
• WARN/FAIL/REFUTED consulted the pawl before any human andon.

Validation

Run the skill and redteam validators:

bash skills/security/scripts/validate.sh
bash tests/scripts/test-security-suite-redteam.sh

For a bounded suite smoke test, use an owned binary and a temporary output directory as shown in the suite runbook.

Examples

• /security — run the quick repository gate, validate its summary, and report coverage/findings.
• /security --release — run the full gate, preserve artifacts, and block promotion until the verdict is green.
• /security run --binary "$(command -v ao)" --out-dir .tmp/security-suite/ao-current — capture an authorized binary baseline via the composable suite.
• /security collect-redteam --repo-root . — run the offline attack pack over repo-owned control surfaces.

Troubleshooting

Problem	Response
Scanner missing/error	Record the coverage gap; install it or rerun with --require-tools when required
Local/CI mismatch	Compare scanner versions, config, mode, and both artifact directories
Suspected false positive	Reproduce narrowly; document any authorized suppression and its owner
Suite/baseline failure	Inspect the named compare/policy artifact; never refresh baseline reflexively
Redteam failure after wording change	Decide whether the control regressed or the attack-pack matcher needs intentional revision

Reference Documents

• references/security-suite-runbook.md — binary/policy/baseline/redteam commands and artifacts
• references/security.feature — repository-gate executable spec
• references/security-suite.feature — composable-suite executable spec
• references/owasp-checklist.md — OWASP Top 10 review
• references/agentops-redteam-pack.json — offline attack pack
• references/policy-example.json — starter policy