aegis

AEGIS — AI Code Auditor Security Skill

When to Use

• Audit codebase security before deployment or release
• Find vulnerabilities in code (SAST-style analysis)
• Security review of pull requests or new features
• Check compliance against OWASP, NIST, CIS, PCI DSS, SOC 2, ISO 27001, GDPR, HIPAA
• Harden project security (headers, validation, hooks, CI/CD)
• Fix security issues with auto/guided transforms
• Threat model an application using STRIDE
• Check for hardcoded secrets or credentials
• Review dependencies for known CVEs
• Generate security headers or Content Security Policy

When NOT to Use

• Runtime/dynamic testing (DAST) — AEGIS is static analysis only, not a runtime scanner
• Network penetration testing — use dedicated pentest tools (Burp, nmap, Metasploit)
• Physical security assessments — out of scope entirely
• Non-code projects — AEGIS needs source code to analyze
• Already-deployed incidents — use incident response tooling, not audit tooling
• Performance testing disguised as DoS checks — AEGIS flags DoS vectors, doesn't load-test

Question System

Before starting analysis, check for these inputs:

| Input | Required | If Missing | |-------|----------|-----------| | Project path / codebase | Yes | Use current working directory. If empty, ask: "Which project should I audit?" | | Engagement mode (RAPID/STANDARD/DEEP) | No | Default to STANDARD. Infer RAPID if user says "quick check" or "PR review". Infer DEEP if "pre-release" or "full audit". | | Specific focus area | No | Audit everything. If user mentions "auth", "uploads", "API", focus STRIDE on those entry points first. | | Compliance frameworks needed | No | Default to OWASP Top 10. Add others if user mentions "SOC 2", "PCI", "HIPAA", etc. | | Fix authorization | No | Always ask before applying auto-fixes. Never fix without confirmation. |

Boot Protocol

1. Identify project: framework, language, stack from package.json/config files
2. Select engagement mode based on user request:
3. RAPID (<15 min): Secrets + deps + top 25 patterns. Use for PR review, quick checks.
4. STANDARD (30-60 min): Full STRIDE + 300 patterns + compliance. Default for "audit my code."
5. DEEP (2-4 hours): Full PASTA + attack trees + supply chain + all infra. Pre-release audits.
6. Build Security Context Object (SCO): entry points, trust boundaries, data flows
7. Execute the three cycles: AUDIT -> FIX -> HARDEN

Foundational Axioms (non-negotiable)

Every finding must trace to one or more:

| # | Axiom | Implication | |---|-------|-------------| | A1 | CIA Triad | Every finding maps to C, I, or A violation | | A2 | Least Privilege | Default-deny. Verify every permission grant | | A3 | Defense in Depth | Single control failure must not cause breach | | A4 | Zero Trust | Every trust boundary crossing requires auth+authz | | A5 | Secure by Default | Detect opt-in to insecure behavior | | A6 | Fail Secure | Error handlers must not leak data or bypass auth | | A7 | Complete Mediation | Every access request must be checked | | A8 | Economy of Mechanism | Flag unnecessary complexity as attack surface | | A9 | Open Design | Security must not depend on obscurity |

CYCLE 1: AUDIT (Detect & Classify)

Phase 1: Reconnaissance — Build SCO

Enumerate automatically:

• Entry points: HTTP routes, WebSocket, file uploads, CLI args, scheduled jobs
• Trust boundaries: client->server, unauth->auth, user->admin, app->db, internal->external
• Data flows: input sources -> transforms -> sinks (trace taint)
• Dependencies: lockfile -> CVE scan
• Infrastructure: Dockerfile, K8s manifests, Firebase rules, Terraform, CI/CD
• Secrets: scan for hardcoded credentials (patterns from references/detection-patterns.md §1)

Compute RASQ (attack surface score):

RASQ = Sum(entry_points x weight x multipliers)
Weights: unauth_http=10, auth_http=5, websocket=8, file_upload=9, webhook=7, server_action=7
Multipliers: handles_PII=x2, internet_facing=x1.5, rate_limited=x0.5, auth_required=x0.7

Phase 2: STRIDE Threat Model

For each entry point and trust boundary, evaluate all 6 STRIDE categories. Load category definitions, key questions, and detection patterns from references/axioms-and-stride.md.

| Category | Violated Property | |----------|------------------| | S Spoofing | Authentication | | T Tampering | Integrity | | R Repudiation | Non-repudiation | | I Info Disclosure | Confidentiality | | D Denial of Service | Availability | | E Elevation | Authorization |

Phase 3: Detection Engine (6 Layers)

Execute in order. Each layer feeds the next.

| Layer | What | Reference | |-------|------|-----------| | 1. SECRET SCAN | Credential pattern matching | references/detection-patterns.md §1 | | 2. DEPENDENCY SCAN | CVE + supply chain analysis | references/detection-patterns.md §2 | | 3. PATTERN MATCH | Code pattern detection by CWE/OWASP | references/detection-patterns.md §3 | | 4. TAINT ANALYSIS | Input source → sink tracing | references/detection-patterns.md §4 | | 5. SEMANTIC REASONING | Context-aware analysis (business logic) | AI-native reasoning | | 6. COMPLIANCE MAP | Framework control verification | references/compliance-matrix.md |

Layer 4 traces untrusted inputs through transforms to sensitive sinks. Load source/sink definitions and neutralizer catalog from references/detection-patterns.md §4.

Phase 4: Risk Scoring (5 Dimensions)

RISK = (Severity x 0.8) + (Confidence x 0.4) + (Exploitability x 0.6) + (Prevalence x 0.2)
       Range: 2.0 to 10.0

PRIORITY = RISK x FIXABILITY_MODIFIER (F=5: x1.05, F=3: x1.0, F=1: x0.95)

ACTION LEVELS:
  8.0-10.0  CRITICAL  Block deployment. Fix immediately.
  6.0-7.9   HIGH      Fix within current sprint.
  4.0-5.9   MEDIUM    Fix within 30 days.
  2.0-3.9   LOW       Fix when touching related code.

Each dimension 1-5:

• Severity: 5=RCE/full breach, 4=significant breach, 3=partial exposure, 2=minor leak, 1=config weakness
• Confidence: 5=certain, 4=strong indicator, 3=likely, 2=possible, 1=anomalous
• Exploitability: 5=single unauth request, 4=auth+standard tools, 3=specific conditions, 2=chained, 1=theoretical
• Prevalence: 5=systemic(>20), 4=widespread(10-20), 3=multiple(3-10), 2=isolated(1-2), 1=single
• Fixability: 5=one-line, 4=config change, 3=module refactor, 2=architectural, 1=design overhaul

Phase 5: Finding Structure

Every finding MUST include:

ID: AEGIS-{STRIDE}-{SEQ}     (e.g., AEGIS-T-001)
Title: descriptive name
STRIDE: S|T|R|I|D|E
CWE: CWE-XXX
OWASP: AXX:2021
Location: file:line, function name
Code snippet: vulnerable code
Scoring: S/C/E/P/F = risk_score -> action_level
Attack scenario: 1-2 sentences
Remediation: fix_type (auto|guided|manual) + secure code
Compliance: which CC-XX checks this resolves

CYCLE 2: FIX (Remedy & Verify)

Fix Classification

| Type | Criteria | Action | |------|----------|--------| | auto | Deterministic transform, Confidence >= 4 | Apply fix. Verify. | | guided | Known transform but context-dependent, Confidence 2-3 | Present fix + explanation. User confirms. | | manual | Architectural change or business decision needed | Document. Provide guidance. User implements. |

Core Transforms (apply via Edit tool)

Load the full transform catalog from references/detection-patterns.md §5. Each transform maps a CWE pattern to its secure equivalent. Apply transforms using the Edit tool. All transforms are deterministic code replacements — no behavioral changes beyond closing the identified gap.

Verification (after every fix)

1. Re-scan the pattern that triggered the finding
2. Run all patterns on the modified file
3. Verify build succeeds (npm run build or equivalent)
4. Check for regressions (new findings introduced)

CYCLE 3: HARDEN (Prevent & Monitor)

Security Headers

Load header configurations and implementation details from `references/hardening.m