Security skills for cloud and AI systems, with OCSF as an option instead of a lock-in. Compose ingest → discover → detect → evaluate → view → remediate like Unix pipes. Run the same skill code from the CLI, CI, MCP, or persistent pipelines.
What it is
- Cross-cloud and AI security skills, not just CSPM
- Read-only by default, least-privilege, zero-trust
- Deterministic, auditable, and grounded in official vendor docs
Run a real bundled fixture through an end-to-end pipeline:
python skills/ingestion/ingest-k8s-audit-ocsf/src/ingest.py \
skills/detection-engineering/golden/k8s_audit_raw_sample.jsonl \
| python skills/detection/detect-privilege-escalation-k8s/src/detect.py \
| python skills/view/convert-ocsf-to-sarif/src/convert.py \
> findings.sarifOr keep the repo-native format for the ingest + detect path:
python skills/ingestion/ingest-k8s-audit-ocsf/src/ingest.py \
--output-format native \
skills/detection-engineering/golden/k8s_audit_raw_sample.jsonl \
| python skills/detection/detect-privilege-escalation-k8s/src/detect.py \
--output-format native \
> findings.native.jsonlStart here
- Agents: AGENTS.md
- Claude Code memory: CLAUDE.md
- MCP usage: docs/agent-integrations.md and
.mcp.json - Architecture and visuals: docs/ARCHITECTURE.md and docs/DIAGRAMS.md
- Runtime isolation and trust boundaries: docs/RUNTIME_ISOLATION.md
- SIEM indexing and dedupe: docs/SIEM_INDEX_GUIDE.md
- Schema modes and interoperability: docs/NATIVE_VS_OCSF.md
- Canonical schema and data flow: docs/CANONICAL_SCHEMA.md and docs/DATA_FLOW.md
- Historical state and timeline handling: docs/STATE_AND_TIMELINE_MODEL.md
- Debugging and troubleshooting: docs/DEBUGGING.md and docs/TROUBLESHOOTING.md
- Coverage and roadmap: docs/COVERAGE_MODEL.md, docs/framework-coverage.json, and docs/ROADMAP.md
| Tool | Best integration path | What to rely on |
|---|---|---|
| Claude Code | CLAUDE.md + AGENTS.md + MCP |
project memory + agent rules + tools |
| Codex | AGENTS.md + MCP |
repo rules + tool calling |
| Cursor | AGENTS.md or .cursor/rules + MCP |
repo rules + tool calling |
| Windsurf | AGENTS.md + MCP |
directory-scoped agent rules + tools |
| Cortex Code CLI | SKILL.md / .cortex/skills + MCP |
native skills + tool calling |
The repo keeps one source of truth:
AGENTS.mdfor universal agent instructionsCLAUDE.mdfor Claude-specific project memorySKILL.mdfor each skill contract- MCP as the access layer, not a second implementation
Visuals
python skills/ingestion/ingest-k8s-audit-ocsf/src/ingest.py audit.log \
| python skills/detection/detect-privilege-escalation-k8s/src/detect.py \
| python skills/view/convert-ocsf-to-sarif/src/convert.py \
> findings.sarif| Layer | Role | Output |
|---|---|---|
| Ingest | Per-source raw payload → canonical model, with optional native / OCSF / bridge output | native JSON, OCSF API / Network / HTTP / Application Activity, or bridge JSON |
| Discover | point-in-time inventory / graph / evidence / AI BOM | deterministic JSON graph, canonical evidence, OCSF inventory/evidence bridge events, or CycloneDX-aligned BOM |
| Detect | canonical or OCSF telemetry → finding + MITRE ATT&CK | Detection Finding (class 2004) or documented native/canonical finding output |
| Evaluate | canonical or OCSF telemetry → framework check | Compliance Finding (class 2003) or documented evidence/check output |
| View | canonical or OCSF → SARIF / Mermaid / graph | GitHub Security tab, PR comments, dashboards |
| Remediate | Finding → action (HITL-gated, audited) | Dual-write audit row |
Each skill is a standalone Python bundle following Anthropic's skill spec: SKILL.md, src/, tests/, REFERENCES.md, explicit Use when..., and explicit Do NOT use....
Schema mode note
- the repo contract supports
native,canonical,ocsf, andbridgemodes - OCSF is a first-class interoperability option, not a mandatory storage format
- the stable repo contract is: preserve source truth, normalize into a canonical internal model, then emit
native,ocsf, orbridgeas appropriate
Currently implemented
- dual-mode (
--output-format ocsf,native):ingest-cloudtrail-ocsfingest-vpc-flow-logs-ocsfingest-k8s-audit-ocsfingest-mcp-proxy-ocsfingest-entra-directory-audit-ocsfingest-google-workspace-login-ocsfingest-okta-system-log-ocsfdetect-lateral-movementdetect-okta-mfa-fatiguedetect-privilege-escalation-k8sdetect-sensitive-secret-read-k8sdetect-mcp-tool-driftdetect-entra-credential-additiondetect-entra-role-grant-escalationdetect-google-workspace-suspicious-login
- native-first with optional bridge:
discover-environmentdiscover-control-evidencediscover-cloud-control-evidence
- OCSF-only today, with format metadata declared for rollout:
- the remaining ingestion and detection skills
- native-only today:
- evaluation and view skills
-ocsf in a skill name means OCSF is the default wire format, not necessarily the only supported mode.
See docs/ARCHITECTURE.md for the full layered design, docs/NATIVE_VS_OCSF.md for schema-mode selection, docs/CANONICAL_SCHEMA.md for the repo-owned canonical contract, docs/DATA_FLOW.md for the end-to-end projection flow, docs/STATE_AND_TIMELINE_MODEL.md for historical-state handling, and docs/DIAGRAMS.md for the visual set.
| Mode | Driver | Best for | Human approval |
|---|---|---|---|
| CLI / just-in-time | Operator or agent runs a skill directly | triage, local analysis, one-off conversions, golden-fixture checks | only for write-capable skills |
| CI | GitHub Actions or another pipeline | regression testing, policy checks, compliance snapshots, SARIF generation | never for read-only skills |
| Persistent / serverless | runner, queue, EventBridge, Step Functions, scheduled jobs | continuous detection, remediation pipelines, lake ingestion | required for destructive actions |
| MCP | local mcp-server/ wrapper |
Claude, Codex, Cursor, Windsurf, Cortex Code CLI | inherited from the wrapped skill |
The important rule is that the skill code does not change between modes. SKILL.md + src/ + tests/ stays the product; the runner, pipeline, or MCP wrapper is only the access path.
execution_modes: persistent means the skill is safe to embed in a persistent runner or serverless loop. It does not mean this repo already ships a dedicated daemon, queue worker, or sink for that skill. Today the only fully shipped persistent workflow is iam-departures-remediation; the broader runner and sink layer remains an explicit roadmap item.
| Skill type | Default posture | Required controls |
|---|---|---|
| Ingest / detect / evaluate / view | read-only | deterministic output, no hidden writes, official references only |
| Discovery / inventory / enrich | read-only unless explicitly documented otherwise | schema validation, output contracts, no secret leakage |
| Remediation | dry-run first | least privilege, blast-radius docs, audit trail, HITL gate |
| Sinks / runners | side-effectful edge components | idempotency, merge-on-UID, transport security, checkpointing |
For every shipped skill, the contract is:
- exact input and output format
- explicit
approval_model,execution_modes, andside_effectsfrontmatter so agents know when to stop for human approval - runtime-aware caller and approver context for write-capable workflows when the wrapper provides it
- explicit
Use when...andDo NOT use... - official vendor docs only in
REFERENCES.md - failure-safe behavior on malformed input and deprecated API shapes
- no generic shell, SQL, or network passthrough
| File | Scope | Use it for |
|---|---|---|
README.md |
public repo overview | what the repo is, how it is positioned, where to start |
AGENTS.md |
cross-agent repo contract | Codex, Cursor, Windsurf, Cortex, Claude, generic AGENTS.md-aware tools |
CLAUDE.md |
Claude Code project memory | repo-wide Claude defaults and working rules |
skills/<layer>/<skill>/SKILL.md |
individual skill contract | when to use a skill, input/output, blast radius, non-goals |
skills/<layer>/<skill>/REFERENCES.md |
source-of-truth references | official docs, schemas, APIs, benchmarks |
Skills shipped today
skills/
├── ingestion/ "Raw source → OCSF 1.8"
│ ├── ingest-cloudtrail-ocsf AWS → API Activity 6003
│ ├── ingest-vpc-flow-logs-ocsf AWS → Network Activity 4001
│ ├── ingest-vpc-flow-logs-gcp-ocsf GCP → Network Activity 4001
│ ├── ingest-nsg-flow-logs-azure-ocsf Azure → Network Activity 4001
│ ├── ingest-guardduty-ocsf AWS → Detection Finding 2004
│ ├── ingest-security-hub-ocsf AWS → Findings 2004 passthrough
│ ├── ingest-gcp-scc-ocsf GCP → Findings 2004 passthrough
│ ├── ingest-azure-defender-for-cloud-ocsf Azure → Findings 2004 passthrough
│ ├── ingest-gcp-audit-ocsf GCP → API Activity 6003
│ ├── ingest-azure-activity-ocsf Azure → API Activity 6003
│ ├── ingest-okta-system-log-ocsf Okta → IAM 3002 / 3001 / 3005
│ ├── ingest-google-workspace-login-ocsf Workspace → IAM 3002 / 3001
│ ├── ingest-k8s-audit-ocsf K8s → API Activity 6003
│ └── ingest-mcp-proxy-ocsf MCP → Application Activity 6002
│
├── discovery/ "Point-in-time inventory and graph evidence"
│ ├── discover-environment → graph JSON or OCSF 5023 inventory bridge
│ ├── discover-ai-bom → CycloneDX-aligned AI BOM
│ ├── discover-control-evidence → PCI / SOC 2 technical evidence JSON
│ └── discover-cloud-control-evidence → Cross-cloud PCI / SOC 2 evidence JSON
│
├── detection/ "What attack pattern does this event stream show?"
│ ├── detect-lateral-movement → T1021 / T1078.004 cross-cloud pivot
│ ├── detect-okta-mfa-fatigue → T1621 Okta Verify push fatigue
│ ├── detect-entra-credential-addition → T1098.001 Entra credential additions
│ ├── detect-entra-role-grant-escalation → T1098.003 Entra app-role grants
│ ├── detect-google-workspace-suspicious-login → T1110 / T1078 Workspace suspicious login
│ ├── detect-mcp-tool-drift → T1195.001 Supply Chain
│ ├── detect-privilege-escalation-k8s → T1552.007 / T1611 / T1098 / T1550.001
│ └── detect-sensitive-secret-read-k8s → T1552.007 Container API
│
├── evaluation/ "Does this align with a benchmark or posture bar?"
│ ├── cspm-aws-cis-benchmark (CIS AWS Foundations v3.0 — 18 checks)
│ ├── cspm-gcp-cis-benchmark (CIS GCP Foundations v3.0 — 7 checks)
│ ├── cspm-azure-cis-benchmark (CIS Azure Foundations v2.1 — 6 checks)
│ ├── k8s-security-benchmark (CIS Kubernetes — 10 checks)
│ ├── container-security (CIS Docker — 8 checks)
│ ├── model-serving-security (20 checks — auth / rate limit / egress / network / safety)
│ └── gpu-cluster-security (13 checks — runtime / driver / tenant isolation)
│
├── view/ "OCSF → reviewable output"
│ ├── convert-ocsf-to-sarif → GitHub Security tab
│ └── convert-ocsf-to-mermaid-attack-flow → PR comments
│
└── remediation/ "Fix it, gated and audited"
└── iam-departures-remediation (event-driven, DLQ + SNS, dual audit)
Roadmap: current open issues focus on AWS Config and deeper evaluation coverage, richer MCP input schemas and transports, additional cloud and AI service coverage, vendor stories, and deeper discovery / inventory follow-ons beyond the first AI BOM and evidence capabilities.
This is a security tool. Trustworthiness is the first feature, not an afterthought. Eleven principles pinned in SECURITY_BAR.md, every skill graded against every principle.
The eleven principles
| # | Principle | What it means |
|---|---|---|
| 1 | Read-only by default | Posture + detection NEVER call write APIs. Remediation isolates the write path behind explicit IAM grants and dry-run defaults. |
| 2 | Agentless | No daemons, no sidecars, no continuously running processes. Short-lived Python scripts that read what's already there. |
| 3 | Least privilege | Each skill documents the EXACT IAM / RBAC permissions it needs in REFERENCES.md. Minimal set only. |
| 4 | Defense in depth | Posture + detection + remediation + audit + re-verify all run in parallel and back each other up. |
| 5 | Closed loop | Every workflow has a verification step: detect → finding → action → audit → re-verify. Drift is itself a detection. |
| 6 | OCSF as default wire format | Ingest and detect skills default to OCSF 1.8 JSONL; native and bridge modes are first-class alternatives declared in each skill's output_formats. MITRE ATT&CK lives inside finding_info.attacks[] when OCSF is emitted. |
| 7 | Secure by design | Security is a first-class input to the skill's architecture, not a bolt-on. |
| 8 | Secure code | Defensive parsing on every input boundary. No eval/exec/pickle.loads on untrusted data. Parameterised SQL only. bandit in CI. |
| 9 | Secure secrets & tokens | No hardcoded creds. Secrets from cloud secret stores. Short-lived tokens. Logs scrub creds. CI greps for AKIA / sk- / ghp_ patterns. |
| 10 | No telemetry | No phone-home. Findings stay local unless the operator explicitly forwards them. |
| 11 | HITL, no rogue behaviour | A skill never escalates its own privileges, never bypasses guardrails, never invokes siblings it wasn't composed with. Destructive actions require HITL gates. |
How trust is verified
| Check | What it catches | Where it runs |
|---|---|---|
| Golden-fixture deep-eq | Silent detection-coverage regressions after a refactor | Per-skill pytest — tests/test_*.py::TestGoldenFixture |
| Wire-contract tests | Off-spec events, wrong class_uid, missing required fields, attacks[] at the wrong level |
Cross-skill assertions pinned in OCSF_CONTRACT.md |
| End-to-end pipes | Breakage across the ingest → detect → convert chain |
tests/integration/ — deep-eq against frozen SARIF + Mermaid |
| Static analysis | Unsafe parsing, missing imports, style drift | ruff check + ruff format --check + bandit on every PR |
| Hardcoded-secret grep | Leaked AKIA… / sk-… / ghp_… tokens before they ship |
CI lint job, repo-wide on every push |
REFERENCES.md per skill |
Fabricated APIs, opaque dependencies, undocumented IAM | Presence enforced by CI; manual review on new skills |
| Skill integrity validator | Name drift, MCP metadata drift, unapproved reference domains, dangerous runtime patterns | scripts/validate_skill_integrity.py in CI and integration tests |
agent-bom scans |
Vulnerable deps, IaC misconfig, shadow AI components | code / skills scan / fs / iac on every push; findings land in GitHub Security tab under agent-bom-iac |
| Document | Purpose |
|---|---|
ARCHITECTURE.md |
9-layer design, two execution modes (stateless + persistent), 10 guardrails |
DIAGRAMS.md |
Architecture map, IAM departures workflow/data flow, and detection pipeline visuals |
CI_WORKFLOW.md |
CI lane layout, dedupe rules, and follow-up simplification plan |
CHANGELOG.md |
Repo-level release notes and material skill changes |
COVERAGE_MODEL.md |
What framework coverage means and how it is measured |
framework-coverage.json |
Machine-readable framework, provider, and asset coverage registry |
FRAMEWORK_MAPPINGS.md |
Where ATT&CK, ATLAS, CIS, NIST, OWASP, SOC 2, ISO, and PCI coverage lives today |
ROADMAP.md |
Coverage and execution roadmap for cloud, AI, and framework depth |
RUNTIME_ISOLATION.md |
Sandbox, credential, transport, integrity, and approval guidance by execution mode |
SIEM_INDEX_GUIDE.md |
Index fields, dedupe keys, timestamps, and transport guidance for OCSF consumers |
DEBUGGING.md |
Common integration failures, format mismatches, and scaling guidance |
TROUBLESHOOTING.md |
Short answers for common operator, reviewer, and CI questions |
mcp-server/README.md |
Thin local MCP wrapper for auto-discovered skills |
DEPENDENCY_HYGIENE_SKILL.md |
Proposed safe dependency-update skill contract |
SKILL_CONTRACT.md |
Minimum files, metadata, and guardrails for shipped skills |
OCSF_CONTRACT.md |
Wire format pinning for OCSF 1.8 + MITRE ATT&CK v14 |
SECURITY_BAR.md |
Per-principle verification matrix — every skill graded against every principle |
SECURITY.md |
Coordinated disclosure policy |
docs/agent-integrations.md |
How Claude, Codex CLI, and AGENTS.md-aware tools should use this repo today |
CONTRIBUTING.md |
How to add a new skill |
New skills land as standalone bundles. The checklist:
- Pick a layer — ingest, discover, enrich, detect, evaluate, remediate, or convert
- Copy the nearest sibling — the existing skills in the target category are the canonical reference layout
- Ship the bundle —
SKILL.mdwith aDo NOT use…clause,src/<entry>.py,tests/test_<entry>.py, golden fixtures underskills/detection-engineering/golden/when the skill speaks OCSF, andREFERENCES.mdlisting every official doc the skill depends on - Add a row to the
SECURITY_BAR.mdmatrix - Wire into CI — add the skill to the right matrix cell in
.github/workflows/ci.yml - Open a PR —
ARCHITECTURE.mdis the review contract; make sure your skill satisfies every applicable guardrail
See CONTRIBUTING.md for the full guide.
Apache 2.0 — use it, fork it, ship it. Security research is welcome; see SECURITY.md for coordinated disclosure.