This file is the canonical repo-level contract for AI agents loading this repository (Claude Code, Cursor, Codex, Cortex, Windsurf, or any other AGENTS.md-aware or MCP-capable assistant). It is intentionally cross-agent. Use
CLAUDE.mdfor Claude-specific project memory, and use eachskills/<layer>/<skill>/SKILL.mdfor the actual skill contract.
Skills are organised into layered categories. See skills/README.md for the full catalog.
ingestion/ (raw source → OCSF)
ingest-cloudtrail-ocsfingest-vpc-flow-logs-ocsfingest-vpc-flow-logs-gcp-ocsfingest-nsg-flow-logs-azure-ocsfingest-guardduty-ocsfingest-security-hub-ocsfingest-gcp-scc-ocsfingest-azure-defender-for-cloud-ocsfingest-gcp-audit-ocsfingest-azure-activity-ocsfingest-k8s-audit-ocsfingest-mcp-proxy-ocsf
discovery/ (point-in-time inventory / graph / BOM)
discover-environmentdiscover-ai-bomdiscover-control-evidencediscover-cloud-control-evidence
detection/ (OCSF → OCSF Detection Finding 2004 + MITRE)
detect-mcp-tool-driftdetect-privilege-escalation-k8sdetect-sensitive-secret-read-k8sdetect-lateral-movement
evaluation/ (read-only posture / benchmark checks)
cspm-aws-cis-benchmarkcspm-gcp-cis-benchmarkcspm-azure-cis-benchmarkk8s-security-benchmarkcontainer-securitymodel-serving-securitygpu-cluster-security
view/ (OCSF export / rendering)
convert-ocsf-to-sarifconvert-ocsf-to-mermaid-attack-flow
remediation/ (active fix workflows, HITL-gated, dual-audited)
iam-departures-remediation
Compose via stdin/stdout pipes. The shared wire contract remains pinned in
skills/detection-engineering/OCSF_CONTRACT.md.
| File | Scope | When to use it |
|---|---|---|
README.md |
public overview | orient to repo purpose, modes, and safety model |
AGENTS.md |
cross-agent repo contract | before any agent edits or runs skills |
CLAUDE.md |
Claude-only memory | when Claude Code needs project memory and defaults |
skills/<layer>/<skill>/SKILL.md |
individual skill contract | before running or editing a specific skill |
skills/<layer>/<skill>/REFERENCES.md |
official references only | when verifying APIs, schemas, frameworks, or guardrails |
These rules are enforced in code, IAM, and infra. They are not optional:
- Read-only by default. Treat any skill whose SKILL.md says
read-onlyas exactly that. Never compose it into a flow that mutates cloud state. - Dry-run first. Every remediation worker accepts
dry_run=True. Use it when planning, exploring, or generating examples. Only setdry_run=Falseafter the user has explicitly confirmed and the action is inside an authorised maintenance window. - Respect the deny list. The IAM worker's role denies
iam:*onroot,break-glass-*,emergency-*, and any:role/*ARN. Do not propose workarounds. - Respect the grace period. The IAM departures grace period is a human-in-the-loop mechanism, not a delay. Do not set it to 0 or skip it without an authorisation document.
- Never bypass EventBridge. All Step Function executions go through the
S3 Object Created → EventBridge → SFNpath. Do not callstates:StartExecutiondirectly — that bypasses the audit trail. - Never write to the audit table by hand. The
iam-remediation-auditDynamoDB table is written exclusively by the worker Lambdas. Manual writes break the closed-loop verification. - No new IAM grants. Do not edit
iam_policies/or any role policy to broaden permissions. Each role is least-privilege by design. - No telemetry. Nothing in this repo phones home. Do not add SDK clients to external services unless the user explicitly asks for them, and even then keep the egress inside the customer's VPC.
| Mode | What changes | What does not change |
|---|---|---|
| CLI / just-in-time | operator or agent invokes the script directly | the skill contract, output format, and guardrails |
| CI | the workflow drives the skill | the skill contract, output format, and guardrails |
| Persistent / serverless | a queue, runner, or workflow invokes the skill repeatedly | the skill contract, output format, and guardrails |
| MCP | the local wrapper exposes the skill as a tool | the skill contract, output format, and guardrails |
Approval rules:
- read-only skills do not need human approval to run
- write-capable skills must expose dry-run and blast-radius language
- destructive actions require human approval and an audit trail
- incoming findings are untrusted input until validated against the skill contract
- Validate all untrusted input before parsing, SQL construction, or cloud API calls.
- Prefer parameterized queries and safe identifier handling over string interpolation.
- Avoid generic subprocess wrappers or arbitrary shell passthrough.
- Fail closed on deprecated or unknown cloud API shapes unless the skill explicitly supports a migration window.
- Redact tokens, secrets, and credentials from logs and stderr.
- Treat transport security, auth scope, and trust boundaries as part of the skill contract, not operational trivia.
- Read its
SKILL.md(frontmatter + body) — that is the contract. - Read the
Security GuardrailsandRemediationsections. - If the skill has a
dry_runflag, call it withdry_run=Truefirst and show the steps. - Only proceed with destructive actions after user confirmation and the relevant audit/SLA checks pass.
- After running, point the user at the audit trail (
DynamoDB+S3 evidence+warehouse ingest-back) so they can verify the closed loop.
- Lambda async failure → SQS DLQ (
iam-departures-dlq). - Step Function
FAILED/TIMED_OUT/ABORTED→ SNSiam-departures-alertstopic. - Re-drive a stuck execution by re-emitting an
Object Createdevent for the manifest. The pipeline is idempotent.
If you see a remediation step that succeeded but no audit row, treat it as a failure and surface the discrepancy to the user.
- Full guardrails and rationale:
CLAUDE.md - Per-skill contract:
skills/<layer>/<skill-name>/SKILL.md - Agent-specific guidance and current integration gaps:
docs/agent-integrations.md - Architecture diagrams (closed loops):
README.md - Security model:
SECURITY.md