A.E.G.I.S

The paranoid audit tool your vibe-coded app deserves.

Stack-specific security scanner for Next.js + Supabase + React. 91 default-enabled scanners (built-in checkers + external-tool wrappers including 19 traditional SAST/DAST tools + 1 passive subdomain-recon + 3 LLM-agent pentest frameworks: Strix, PTAI, Pentest-Swarm-AI) plus 5 opt-in active attack-probes, AST-based cross-file taint analysis, 0-1000 score with FORTRESS → CRITICAL grade. Best used alongside Semgrep / CodeQL — not instead of them. Ships a CLI, MCP server, and a GitHub-Actions recipe for CI integration.

What is AEGIS?

AEGIS (Automated Enterprise-Grade Inspection Suite) finds vulnerabilities that generic SAST tools miss because they lack framework-specific rules. AEGIS covers the Next.js / Supabase / React gaps — multi-tenant isolation, RLS bypass, Server Component data leaks, Zod enforcement, .rpc() SQLi, mass assignment, auth-guard gaps — while Semgrep / CodeQL cover the generic SAST space.

What makes the engine different: AEGIS tracks data flow through your code — within a file AND across module boundaries:

// Same-file taint:
const id = req.body.id;                            // source: user input
const trimmed = id.trim();                         // propagates through method call
const query = `SELECT * WHERE id = ${trimmed}`;    // propagates through template
db.query(query);                                   // sink: SQL Injection (CWE-89, CRITICAL)

// Cross-file taint:
// lib/db.ts     — export function runQuery(sql: string) { db.query(sql); }
// api/route.ts  — import { runQuery } from '../lib/db';
//                 runQuery(req.body.q);           // AEGIS traces the sink across the boundary

Per-CWE sanitizer awareness: parseInt() blocks SQL injection but not XSS, DOMPurify.sanitize() blocks XSS but not SQL injection, encodeURIComponent() blocks SSRF but not path traversal (frameworks decode before fs access).

Suite composition: 91 default-enabled scanners in the static-analysis pipeline (built-in regex + AST taint analyzer + RPC-specific SQLi scanner + 16 external tool wrappers: Semgrep, Gitleaks, ZAP, Trivy, Nuclei, Bearer, Checkov, Hadolint, TruffleHog, OSV-Scanner, testssl.sh, React Doctor, Lighthouse, Axe, …), 5 opt-in live attack probes (aegis siege / pentest with --confirm), 4 compliance frameworks (GDPR / SOC 2 / ISO 27001 / PCI-DSS), an MCP server for AI agents, and a reusable GitHub-Actions recipe (at ci/github-action/) that posts PR comments with the score + top findings.

Architecture

                   ┌──────────────────┐
                   │ aegis.config.json│ ← user config (optional)
                   └────────┬─────────┘
                            │
                   ┌────────▼─────────┐
                   │   ConfigLoader   │ (@aegis-scan/core)
                   │  (Zod-strict)    │
                   └────────┬─────────┘
                            │
                   ┌────────▼─────────┐
                   │   Orchestrator   │ walkFiles → per-scanner dispatch
                   └────────┬─────────┘
                            │
             ┌──────────────┼──────────────┐
             ▼              ▼              ▼
  ┌──────────────────┐  ┌────────────┐  ┌──────────────────┐
  │ Built-in scanners│  │  Taint     │  │ External wrappers│
  │  (41 regex rules)│  │  Analyzer  │  │  (Semgrep, ZAP, …│
  │                  │  │  (AST +    │  │   auto-skip when │
  │                  │  │   TS       │  │   not installed) │
  │                  │  │   Compiler)│  │                  │
  └─────────┬────────┘  └─────┬──────┘  └────────┬─────────┘
            │                  │                  │
            └─────────────┬────┴──────────────────┘
                          ▼
                ┌──────────────────┐
                │     Findings     │
                └─────────┬────────┘
                          │
                ┌─────────▼──────────┐
                │ Suppression filter │ ← inline + config suppressions
                └─────────┬──────────┘
                          │
                ┌─────────▼──────────┐
                │  Score / Grade /   │ ← 0-1000, blocker override
                │  Badge / Confidence│
                └─────────┬──────────┘
                          │
              ┌───────────┼───────────┐
              ▼           ▼           ▼
          Terminal      JSON       SARIF 2.1.0
          (colour)   (machine)     (GH Code
                                    Scanning)
                          │
                          ▼
                     HTML / Markdown
                     (dashboards, PR comments)

The taint analyzer is the cross-cutting sibling to the regex scanners: it parses each file with the TypeScript Compiler API, walks the AST to find source → sink flows, consults the module-graph + function-summary cache for cross-file propagation, and emits its findings into the same pipeline. Every scanner reads from @aegis-scan/core and writes into the shared Finding[] array; the Orchestrator owns scheduling and the score aggregator owns the final verdict.

Quick Start

npx @aegis-scan/cli scan .

# Or install globally
npm install -g @aegis-scan/cli
aegis scan .

# Full audit with all scanners
aegis audit .

# Generate config
aegis init .

New to AEGIS? The
Getting Started guide walks you from
zero-install to your first scan, config, false-positive handling, MCP
setup, and CI integration in about 5 minutes.

Scaffold a new project

Starting a Next.js + Supabase project? Skip the security-retrofit
phase — let AEGIS lay down a production-ready foundation from commit 0.

aegis new my-saas

The scaffold ships with:

• 11 clean-room security primitives — secureApiRouteWithTenant,
  requireRole (RBAC), rate-limit (X-Forwarded-For-aware), SSRF-safe
  fetch, AES-256-GCM crypto, Zod-strict schemas, PII-sanitizing
  logger (50+ redaction patterns), AppError hierarchy.
• RLS bootstrap migration — tenants + profiles tables with
  strict policies + auto-profile-on-signup trigger.
• Hardened middleware — CSRF + 9 security headers
  (incl. COEP / COOP / CORP) + rate-limit.
• Exemplary API route (59 LoC) composing all 6 primitives — teaches
  the composition pattern at scale, with correct error-mapping
  (ForbiddenError → 403, ZodError / SyntaxError → 400).
• GitHub Action PR-gate with mode: audit + pinned Semgrep /
  OSV-Scanner / Gitleaks / TruffleHog pre-installs (SHA-256 verified).
• AI-safety rules (CLAUDE.md) for AI coding assistants.
• Husky pre-push hook running aegis scan --fail-on-blocker.

Baseline: a fresh scaffold scores 997/A HARDENED with
0 BLOCKER (empirically verified — npm install + aegis scan
end-to-end). The 5 MEDIUM baseline findings — 2 scanner-FPs (scheduled
for v0.13 scanner-fixes) + 3 Next.js-ecosystem-inherent supply-chain
items — are documented in the scaffold's own README under "Known
baseline findings": pedagogy, not suppression.

Retrofit an existing project:

aegis init

Writes aegis.config.json + .github/workflows/aegis.yml +
CLAUDE.md + .husky/pre-push into the current directory.
Skip-if-exists by default (never clobbers user files). Use --force
to overwrite the three extension files uniformly, or --skip-ci /
--skip-claude / --skip-husky to opt out per file. Partial-write-
safe: successful writes stay on disk if a later write fails — the
command modifies the user's project, so it never rolls back.

See the v0.12 scaffolding-pivot design spec
for template structure, primitive source-strategy, and exit criteria.

AEGIS is a three-layer security toolkit

AEGIS ships three sibling packages that cover the full pre-ship security lifecycle. Serious security teams use all three together.

Build with the wizard. Scan what you built. Test it red-team-style. Full lifecycle, one toolchain, one attribution-compliant open-source license stack. The three packages release independently (wizard-v*, v*, and skills-v* tag-namespaces) so neither gates the other — but they co-calibrate on architectural assumptions: a wizard-scaffolded project scoring below 960 on scan's grade is treated as a pattern-defect, and an agent running under the skills library can reach for attack classes scan detects defensively.

# One-shot full-repertoire workflow
npx -y @aegis-wizard/cli new my-saas --interactive   # build
npx -y @aegis-scan/cli scan ./my-saas                # scan
npm i -g @aegis-scan/skills && aegis-skills install  # equip agent for test

See the individual package READMEs for full docs:

• packages/wizard-cli/README.md
• packages/skills/README.md
• docs/patterns/index.md for the wizard's bundled pattern catalog

Responsible-use for @aegis-scan/skills is documented in this repository's SECURITY.md — the offensive methodology library is authorized-testing-only.

What AEGIS finds that generic SAST tools miss

These are stack-specific vulnerabilities in Next.js + Supabase apps. Generic tools don't have rules for them because they're framework-specific patterns:

AEGIS is not a Semgrep replacement — it's a Semgrep multiplier. When Semgrep is installed, AEGIS wraps it automatically and you get both.

Real-world corpus

AEGIS is tuned against an 8-project public-source corpus. Each finding
is manually annotated TP/FP and the recurring FP patterns are pinned
as regression tests. Scores below are the frozen v0.11.2 baseline —
a fresh corpus run on the v0.17 line is scheduled for the next minor
release. The methodology, FP-classification rigor, and tuning posture
are unchanged; absolute numbers may shift slightly with the post-v0.11.2
precision improvements (Field-Report Sub-Klassen 1-4, scanner-family
dogfood-driven fixes through v0.16.x).

v0.11.2 movement vs v0.11.1: |Δ| max = 0 points, 0 grade shifts.
The change set is a narrow scanner-precision fix (tenant-isolation-checker
comment-prose strip + recall widen + URL-param-scope suppression). The
suppression branches only fire on a specific AST shape not present in
these projects — corpus scores are strictly unchanged. The dogfood
project driving the release: 8 tenant-isolation-checker FPs → 0.

v0.11.1 movement vs v0.11.0: |Δ| max = 3 points, 0 grade shifts.
The change set is dogfood-driven — a real-world Next.js+Supabase scan
surfaced 5 distinct auth-enforcer + ssrf-checker FP classes not on
the v0.11 speculative roadmap. The dogfood project itself moved
940/A → 946/A with 6 false-positive findings eliminated. The small
midday drift (−3) is category-cap arithmetic from reduced ssrf
emissions — noise-level, grade unchanged.

v0.11.0 movement vs v0.10.0: |Δ| max = 1 point, 0 grade shifts.
The same change set closed +4 synthetic-recall canaries, taking
the 27-canary harness to 27/27 full green for the first time.
Interpretation: precision on real-world corpora stayed stable while
recall on documented CWE / scanner gaps improved. The dual view is
intentional — a precision-only read would call a tool "good" for not
changing scores, which is circular.

*supabase-studio retains two BLOCKER findings on legitimate SQL
string-concatenation in shipping source (Reports.constants.ts and
Logs.utils.ts). These are not false positives — a Supabase-internal
admin dashboard with a different threat model than a customer-facing
app, but the findings are accurate as written.

Corpus-driven fixes in v0.11.0 (analyzer-core consumer-side symmetry +
new scanner + precision tweaks; details in
CHANGELOG.md):

• New ast/guard-flow.ts module — shared dominator-walk between
  function-summary (v0.9.1 builder-side) and taint-tracker (v0.11
  consumer-side). Closes D4 (named-fn URL guard) + D5 (startsWith-
  literal guard) + Z3 (cross-file consumer-side guard symmetry) via
  a single isSinkGuardedByKnownPredicate wired into three sink-
  emission call sites.
• New scanner middleware-auth-checker — Next.js middleware auth-
  bypass CVE-2025-29927 via x-middleware-subrequest header.
  Bumps built-in scanner count 40 → 41.
• ssrf-checker structural SAFE_PATTERN for user-defined typed URL
  guards (name token + : boolean return). Silences ssrf-checker
  on D4-shape allowlist helpers — both scanners now fall silent in
  tandem on the same structural signal.
• ssrf-checker library-wrapper heuristic (Z4) — exported fetch-
  wrappers where the URL is a parameter no longer emit CWE-918 at
  the wrapper site.
• timing-safe-checker UPPERCASE env-var name allowlist widened to
  cover the common process.env.SECRET shape.
• Canary-based recall measurement — packages/benchmark/canary- fixtures/ is a 27-canary harness covering 5 harness-validation +
  10 deferred-item targets + 12 blind-spot stressors. 23/27 pass
  post-v0.10; the remaining 4 (D4 / D5 taint-analyzer guard-flow,
  S1 CVE-2025-29927 middleware bypass, S12 timing-safe var-name
  allowlist) are explicit v0.11 scope.

Honest limitations

Running a security tool is a trust exercise. Here is what AEGIS does not do well — or at all — documented up front so you can decide where AEGIS fits in your stack:

• Cross-file taint precision is unmeasured at scale. The current dogfood corpus (6 production Next.js codebases) has too few cross-file emissions to produce a statistically valid precision number. Cross-file findings therefore ship with confidence: 'medium' rather than the default. Same-file taint is measured by the benchmark (30/30 strict) and is the engine's primary strength.
• Not a general SAST replacement. AEGIS is stack-specific. On Python / Go / Rust / Java it does nothing useful. On non-Next.js Node it still covers the generic classes (SQLi, SSRF, path traversal, prompt injection, crypto misuse) but skips the framework-specific rules. Use alongside Semgrep / CodeQL / njsscan, never instead.
• Compliance checks are pattern-based rules, not audit-grade. gdpr-engine, soc2-checker, iso27001-checker, pci-dss-checker cover dozens of the most common pattern-level controls (e.g. GDPR: privacy page, cookie consent, PII handling, self-hosted fonts, double-opt-in, retention). They are not a substitute for a certified auditor.
• TypeScript / JavaScript only. No Python / Go / Rust / Java / C# / Ruby / PHP.
• External-tool wrappers require the tool on PATH. Semgrep / Gitleaks / Trivy / ZAP / OSV-Scanner / … integrations auto-skip when the underlying binary is absent. The CLI reports Confidence: LOW with a "Missing: …" note, and the CI PR-comment badge gets a [LOW-CONFIDENCE] prefix, when no security-focused external tool is available.
• Single-maintainer project. CONTRIBUTING / SECURITY / CODE_OF_CONDUCT / CODEOWNERS / issue templates are in place; contributions and review help welcome.

OWASP-APTS Conformance Posture

AEGIS publishes a public OWASP Autonomous Penetration Testing Standard
(APTS) Tier-1 Readiness Assessment — the first OSS pentest platform with
a published APTS conformance posture.

This is a transparent gap statement, not a conformance claim. APTS
forbids partial credit; a Tier-1 conformance claim requires 100% MET on
all 72 Tier-1 requirements. AEGIS today meets 57 of 72 Tier-1 requirements
(79% — Phase-1 baseline + Phase-2 Clusters 1 + 2 + 3 + 4 + 5 + 6 shipped,
with three fully-met domains (SE 9/9, MR 13/13, RP 3/3) and Human
Oversight at 11/13) and the readiness assessment is honest about where
the remaining 15 gaps are, with concrete closure plans (Phase-2.5 and
Phase-3) for each.

• Tier-1 Readiness Assessment
• Gap summary (TL;DR)
• Machine-readable claim (conformance.json)
• Evidence manifest
• Foundation model disclosure (BYOM)

Phase 2 (Tier-1 Full Conformance Claim — close all Tier-1 gaps): 8-12
weeks. Phase 3 (Tier-2 Climb): post Phase 2.

The conformance posture covers the AEGIS Autonomous Pentest Layer
(aegis siege + LLM-pentest wrappers Strix/PTAI/Pentest-Swarm-AI + CLI
orchestration). The deterministic SAST scanners, the @aegis-scan/skills
methodology package, and the @aegis-wizard/cli scaffold are supporting
components and explicitly out-of-scope for this conformance posture.

Taint Analysis Engine

The AST-based taint tracker uses the TypeScript Compiler API to follow user input through your code — within a single file and across module boundaries.

Per-CWE sanitizer awareness:

Cross-file propagation — a function-summary cache lets the tracker follow taint into an imported function, check whether any parameter reaches a sink (and with which CWE), and emit a finding at the caller's file with a relatedLocations pointer back to the origin file. Supported patterns:

• Bare-identifier callees: import { runQuery } from './lib'; runQuery(tainted);
• Arrow-function-variable exports: export const fn = (x) => sink(x);
• Default exports: export default function (x) { sink(x); }
• Declaration-style exports: export { foo }; / export { foo as bar };
• Barrel re-exports up to depth 5.
• HOC / curry binding sites (withAuth((cmd) => exec(cmd))) emit at the binding line.
• Generic pass-through return-taint (identity<T>(x: T): T).
• Method-call cross-file callees (import { db }; db.query(tainted)) via TypeChecker resolution.
• Conditional-import downgrade — confidence: 'medium' when the callee module is ternary / if-else dynamic-imported.
• Cross-file sanitizer recognition — imported wrappers that parseInt() / z.parse() / etc. their arg suppress the finding.
• Regex-guard filter — if (!regex.test(x)) return; before an SSRF sink drops CWE-918.
• SSRF URL-position check — only the first fetch(url, …) arg counts; tainted values in headers/body do not.

Scan Modes

Three-tier model — each tier is a strict superset of the previous:

• Static SAST: ~50 scanners covering security / deps / quality / compliance — pure local code analysis, no traffic to any target. Same scanner set in scan and audit (audit applies deeper external-wrapper invocation when their CLIs are installed).
• DAST scanners: ZAP / Nuclei / Strix / PTAI / Pentest-Swarm. Send live HTTP probes / requests to the --target URL. Mode-gated on mode === 'pentest' || 'siege' — the audit and scan commands cannot invoke them even if --target is set (--target on those is a no-op for DAST).
• Active probes: 5-tuple auth-probe / header-probe / rate-limit-probe / privesc-probe / race-probe from getAttackScanners(). Only siege invokes them.

⚠ Active-mode authorization (pentest / siege) — both modes send
LIVE HTTP TRAFFIC to the URL passed via --target. Only run against
systems you own or have written authorization to test. Unauthorized
active probing of third-party systems may violate the Computer Fraud
and Abuse Act (US 18 USC §1030), §202a-c StGB (DE), the Computer
Misuse Act 1990 (UK), and equivalent statutes worldwide. The
--confirm flag is the operator's acknowledgement of authorization;
AEGIS records the timestamp to stderr (and to --state-file when
configured for siege — pentest has no --state-file) for
audit-trail purposes. The reachability probe in both modes uses
safeFetch with SSRF / DNS-rebinding / cloud-metadata defenses;
--allow-loopback opts in to local dev-server targets. Static modes
(scan / audit / fix / history / diff) are pure local code
analysis — no network traffic to any --target.

Scanners (67 total)

Authoritative registration: getAllScanners() + getAttackScanners() in
packages/scanners/src/index.ts. Counts
below are re-verified at every release per the release checklist.

Built-in (91 default-enabled scanners + 5 opt-in active attack-probes + scanner→skill linkage)

External wrappers (20 scanners, auto-skipped when not installed)

Attack probes (5, siege mode only)

auth-probe, header-probe, rate-limit-probe, privesc-probe, race-probe

Scoring

BLOCKER and CRITICAL severity are semantically equivalent — both represent the highest-severity tier and both force the score to 0 / grade F immediately, regardless of other findings. Scanners may emit either label; the scoring engine treats them identically (this was unified in v0.15.1 after an external review surfaced scans returning grade S with a critical finding quietly buried in the table). Examples of findings that fall into this tier: eval injection, hardcoded secrets, unauthed admin routes, service-role-key misuse, SQL injection on unscoped queries.

MCP Server — use AEGIS from any AI coding agent

AEGIS ships a Model Context Protocol server so AI coding agents (Claude Code, Cursor, Continue, Zed, …) can run scans, query findings, and check compliance posture directly from the conversation. Install locally, then register the server in your agent's MCP config.

Install:

npm install -D @aegis-scan/mcp-server

Register (Claude Code — ~/.config/claude-code/mcp.json, Cursor — .cursor/mcp.json, etc.):

{
  "mcpServers": {
    "aegis": {
      "command": "npx",
      "args": ["-y", "@aegis-scan/mcp-server"]
    }
  }
}

Tools exposed (callable from the agent without leaving the chat):

Low-friction for developers who already run Claude Code / Cursor — your assistant can now scan and triage without a context-switch.

CI/CD — GitHub Action

Drop-in security gate for any GitHub Actions workflow. Posts a PR comment with score, severity table, and top findings; fails the build when the score drops below a configurable threshold.

Distribution note: the action lives in-repo at ci/github-action/action.yml (not published to the GitHub Marketplace). Consumers reference it via uses: RideMatch1/a.e.g.i.s/ci/github-action@<tag> pinning to a released tag (e.g. v0.16.6).

name: Security
on: [push, pull_request]
jobs:
  aegis:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: RideMatch1/a.e.g.i.s/ci/[email protected]  # pin to a specific release tag
        with:
          mode: scan           # 'scan' (quick) or 'audit' (full)
          path: .              # project to scan (default: '.')
          fail-below: 700      # set to 0 to never fail the build
          comment-on-pr: true  # post PR comment with findings table

Inputs: mode, path, fail-below, comment-on-pr, upload-sarif, diff-against, aegis-version. See ci/github-action/action.yml for the full schema. Always pin to a specific release tag (@v0.16.6) rather than @main — a floating ref can silently break CI when AEGIS itself updates.

Contributing

See CONTRIBUTING.md for development setup, workflow, and scope boundaries. Security issues: SECURITY.md.

Bug reports and feature requests welcome via GitHub Issues; broader design questions via Discussions.

Credits

See CREDITS.md for full attribution of integrated tools and inspirations.

License

MIT