{"id":51079055,"url":"https://github.com/maxgfr/ultrasec","last_synced_at":"2026-06-23T16:33:06.975Z","repository":{"id":365304143,"uuid":"1271510877","full_name":"maxgfr/ultrasec","owner":"maxgfr","description":"Cross-file security audit agent skill — trace untrusted data across functions and files (source-to-sink taint), orchestrate Trivy/Semgrep/gitleaks/osv-scanner, and adversarially verify findings into a cited, tiered report. Sibling of ultraindex/ultrasearch.","archived":false,"fork":false,"pushed_at":"2026-06-16T20:10:55.000Z","size":202,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-16T20:22:44.176Z","etag":null,"topics":["agent-skill","ai-agent","appsec","claude","code-audit","devsecops","sast","security","skills","static-analysis","taint-analysis","vulnerability-scanner"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maxgfr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-16T18:28:48.000Z","updated_at":"2026-06-16T20:11:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/maxgfr/ultrasec","commit_stats":null,"previous_names":["maxgfr/ultrasec"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/maxgfr/ultrasec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgfr%2Fultrasec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgfr%2Fultrasec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgfr%2Fultrasec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgfr%2Fultrasec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maxgfr","download_url":"https://codeload.github.com/maxgfr/ultrasec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgfr%2Fultrasec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34698696,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skill","ai-agent","appsec","claude","code-audit","devsecops","sast","security","skills","static-analysis","taint-analysis","vulnerability-scanner"],"created_at":"2026-06-23T16:33:06.849Z","updated_at":"2026-06-23T16:33:06.966Z","avatar_url":"https://github.com/maxgfr.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ultrasec\n\n\u003e Cross-file security audit for whole repos — trace untrusted data across\n\u003e functions and files, orchestrate best-in-class OSS scanners, and adversarially\n\u003e verify every finding into a cited, tiered report.\n\n`ultrasec` is an [agent skill](https://skills.sh) in the `ultra*` family\n(sibling of [ultraindex](https://github.com/maxgfr/ultraindex) and\n[ultrasearch](https://github.com/maxgfr/ultrasearch)). It follows the same\ndivision of labour:\n\n- a **deterministic, zero-dependency engine** (`scripts/ultrasec.mjs`, run with\n  `node`, no `npm install`, no API keys) does the mechanical work — scan the\n  repo, build a **cross-file/function link-graph**, enumerate candidate\n  **source→sink taint paths**, run + normalize whatever external scanners are\n  installed, **correlate** their findings across tools (one issue, not three),\n  **rank** every finding by composite **EPSS · CISA KEV · CVSS risk**, and\n  assemble per-finding **evidence packets**;\n- the **AI** does the security reasoning — judge which candidate flows are real\n  and exploitable across files, find the subtle authz/business-logic bugs the\n  tools miss, and **adversarially verify** each finding (conservatively — an\n  uncertain high-severity stays `needs-human`, never auto-dismissed).\n\nWhy it exists: deterministic engines that do cross-file taint (CodeQL global\nflow, Semgrep Pro, Joern) are precise but gate it behind paywalls and miss\nbusiness-logic flaws; pure-LLM scanners hallucinate and are diff-scoped.\n`ultrasec` occupies the middle ground — an **explicit cross-file link-graph**\nplus **adversarial AI verification** — and stays whole-repo and anti-hallucinating\n(every finding must cite resolvable `[file:line]` hops).\n\n## Install\n\n**As an agent skill** (Claude Code, Cursor, … via [skills.sh](https://skills.sh)):\n\n```bash\nnpx skills add maxgfr/ultrasec\n```\n\nThis drops `SKILL.md` + the `references/` + the committed `scripts/ultrasec.mjs`\nbundle into your agent's skills directory. Your agent then triggers it on\n\"audit this repo for security\", \"find vulnerabilities\", etc.\n\n**Standalone** (just the CLI — no agent needed):\n\n```bash\ngit clone https://github.com/maxgfr/ultrasec \u0026\u0026 cd ultrasec\nnode scripts/ultrasec.mjs --help          # the committed bundle runs as-is (zero deps, Node \u003e= 18)\n```\n\n**From the release tarball:** grab `ultrasec-\u003cversion\u003e.tgz` from the\n[latest release](https://github.com/maxgfr/ultrasec/releases), `tar xf` it, and\nrun `node package/scripts/ultrasec.mjs`.\n\nNo `npm install`, no API keys — the engine is a single dependency-free bundle.\nExternal scanners are optional and auto-detected (see [Docker](#analysis-tools-via-docker) below).\n\n## Quick start\n\n```bash\nnode scripts/ultrasec.mjs tools                       # installed scanners + how to get the rest\nnode scripts/ultrasec.mjs context --repo . --out .ultrasec   # project-context primer → author CONTEXT.md\nnode scripts/ultrasec.mjs scan --repo . --out .ultrasec   # graph + cross-file taint + tools → dossier\nnode scripts/ultrasec.mjs triage --run .ultrasec      # cheap noise/keep fast-lane (apply: --apply TRIAGE.json)\nnode scripts/ultrasec.mjs dossier \u003cid\u003e --run .ultrasec    # one finding's real code + path (adjudicate)\nnode scripts/ultrasec.mjs investigate --run .ultrasec     # hunt authz/business-logic; ingest grounded Discovery[]\nnode scripts/ultrasec.mjs verify --run .ultrasec      # adversarial worklist → write verdicts.json\nnode scripts/ultrasec.mjs verify --apply verdicts.json --run .ultrasec\nnode scripts/ultrasec.mjs revalidate --run .ultrasec  # git-history false-positive cut (apply: REVALIDATE.json)\nnode scripts/ultrasec.mjs check --run .ultrasec --semantic   # exit gate: grounded + adjudicated\nnode scripts/ultrasec.mjs narrative --run .ultrasec   # author NARRATIVE.json (exec summary, fixes, chains)\nnode scripts/ultrasec.mjs render --run .ultrasec --narrative NARRATIVE.json   # SUMMARY/REPORT/FULL.md + index.html\nnode scripts/ultrasec.mjs implement --run .ultrasec   # remediation-PRD draft (IMPLEMENT.md) → feed to the to-prd skill\n```\n\n`context`, `triage`, `investigate`, `revalidate`, `narrative`, `implement` are additive — a quick\naudit can skip them. To sequence the whole pipeline (and, opt-in, drive your own agent\nCLI to fill the worklists), use `run`:\n\n```bash\nnode scripts/ultrasec.mjs run --repo . --out .ultrasec    # emits every worklist + a TODO; ZERO external calls\nnode scripts/ultrasec.mjs run --repo . --powered --agent claude --cross-check codex   # autonomous (keys live in the CLI)\n```\n\nNothing external is required — the link-graph and taint reasoning are the\nalways-on core. Installed scanners (Trivy, OpenGrep/Semgrep, gitleaks,\nosv-scanner, cargo-audit, govulncheck, **bandit, gosec, checkov, hadolint,\nkingfisher**, …) are an automatic bonus, normalized into one finding model,\n**de-duplicated across tools**, and **risk-ranked** (EPSS exploit-probability +\nCISA KEV + CVSS). Risk scoring uses cached, offline-friendly feeds — add\n`--no-enrich`/`--offline` to skip the network and rank by severity alone.\n\nSee [`assets/example-audit/`](assets/example-audit/) for a complete run, and\n[`SKILL.md`](SKILL.md) + [`references/`](references/) for the agent workflow\n(including the [deep-audit playbook](references/deep-audit-playbook.md)).\n\n### Large repos (millions–billions of LOC)\n\nDon't scan the whole tree — **map the attack surface, then drill in under a budget**:\n\n```bash\nnode scripts/ultrasec.mjs map  --repo . --out .ultrasec                       # rank targets by sink density\nnode scripts/ultrasec.mjs scan --repo . --scope \u003cdir\u003e --merge --resume --out .ultrasec   # drill one target into the same run\nnode scripts/ultrasec.mjs scan --repo . --diff origin/main --merge --resume --out .ultrasec  # incremental: only changed files + reverse-deps\n```\n\n`--scope`/`--include`/`--exclude`/`--max-files`/`--gitignore` prune the walk;\n`--budget quick|standard|thorough` (and `--max-candidates`/`--max-depth`)\nrank-then-cap candidates (truncation is reported, never silent); `--merge` folds a\nscoped pass into one dossier (preserving prior verdicts); `--resume` reuses a\ncontent-hashed scan cache. Full loop: [scale-audit playbook](references/scale-audit-playbook.md).\n\n## Extra recall, provenance \u0026 deepsec interop\n\nThree opt-in additions, all keeping the zero-dependency / no-API-key core intact:\n\n```bash\nnode scripts/ultrasec.mjs scan --repo . --sinks --out .ultrasec   # orphan-sink recall\nnode scripts/ultrasec.mjs scan --repo . --blame --out .ultrasec   # git-blame + CODEOWNERS provenance\nnode scripts/ultrasec.mjs import findings.json --run .ultrasec    # ingest a deepsec export\n```\n\n- **`--sinks` (orphan-sink recall).** The taint pass only emits a finding when it can\n  connect a dangerous sink *back* to an untrusted source. `--sinks` adds every sink it\n  **can't** connect (single-file scripts, framework dispatch the summary-graph misses,\n  config-fed sinks) as a low-confidence `sast` candidate — capped and truncation-reported\n  like taint, adjudicated the same way.\n- **`--blame` (provenance).** Attaches deterministic git-blame author/commit/author-date +\n  CODEOWNERS owner to each finding — a triage signal (\"introduced last week by X, owned by\n  team Y\"). Reproducible (author-date, not wall-clock) and **evidence only**: it never culls\n  a finding by age.\n- **`import` (deepsec interop).** [vercel-labs/deepsec](https://github.com/vercel-labs/deepsec)\n  is an agent-powered scanner that drives its *own* LLM. Rather than vendor it (it needs API\n  keys + an Apache-2.0 dependency, against ultrasec's grain), ultrasec **ingests its output**:\n  run `deepsec export --format json` yourself, then `ultrasec import` maps each finding into\n  the unified model, correlates it against the engine/scanner findings, risk-ranks it, and\n  runs it through the same `[file:line]` grounding gate and conservative verify flow — making\n  ultrasec the deterministic referee over deepsec's non-deterministic agent output. No keys,\n  no Vercel, no deepsec process spawned by ultrasec. Correlation goes deeper than dedup: a\n  deepsec hit whose `file:line` lands on a node of an engine **taint path** corroborates that\n  flow in place (its `sources` gains `deepsec`, confidence bumps, the path is untouched), and\n  deepsec's revalidation reasoning/verdict is carried as a clearly-labelled **`priorAnalysis`\n  signal** (shown in the dossier + verify worklist, but it never changes a status — your\n  verify gate does).\n\n## Analysis tools via Docker\n\nultrasec orchestrates best-in-class OSS scanners and normalizes their output into\none finding model. You don't have to install any of them — two Docker paths:\n\n**1. `--docker` (zero install).** ultrasec runs each scanner from its official,\nversion-pinned image on demand, with your repo bind-mounted at `/work`:\n\n```bash\nnode scripts/ultrasec.mjs scan --repo . --out .ultrasec --docker\n# runs, via docker: trivy, gitleaks, osv-scanner, semgrep, bandit, gosec,\n# checkov, hadolint — whatever has an official image\nnode scripts/ultrasec.mjs scan --repo . --docker --tools trivy,gitleaks   # pick a subset\n```\n\nOnly Docker is required. Reported paths are rewritten from `/work` back to\nrepo-relative automatically. Pinned images: `ghcr.io/aquasecurity/trivy:0.71.1`,\n`ghcr.io/gitleaks/gitleaks:v8.30.1`, `ghcr.io/google/osv-scanner:v2.3.8`,\n`semgrep/semgrep:1.166.0`, `ghcr.io/pycqa/bandit:1.8.6`,\n`ghcr.io/securego/gosec:v2.21.4`, `bridgecrew/checkov:3.2.0`,\n`hadolint/hadolint:v2.12.0`.\n\n**2. Toolbox image (everything baked in).** Build one image with the engine + all\nbundled scanners and run the whole audit inside it:\n\n```bash\ndocker compose build\nTARGET=/path/to/repo docker compose run --rm ultrasec scan --repo /work --out /work/.ultrasec\nTARGET=/path/to/repo docker compose run --rm ultrasec tools     # all show ✓ installed\n```\n\nSee [`references/tools.md`](references/tools.md) for the full scanner matrix,\nthe correlation/risk-scoring layers, and recommended additions (GuardDog for\nmalicious packages, TruffleHog for live secret verification, cppcheck for C/C++).\n\n## Cleanup\n\nultrasec never installs anything globally, and you can remove everything it\ncreated — straight from the script — when you're done:\n\n```bash\nnode scripts/ultrasec.mjs clean --run .ultrasec            # remove the audit dossier\nnode scripts/ultrasec.mjs clean --run .ultrasec --docker   # + pulled scanner images, toolbox image, trivy cache volume\nnode scripts/ultrasec.mjs clean --docker --dry-run         # preview what would be removed\n```\n\n`clean --docker` removes only the artifacts ultrasec is responsible for (the\npinned scanner images, `ultrasec-toolbox`, and the `*trivy-cache*` volume) — your\nother Docker images are untouched. The compose stack tears down the same way with\n`docker compose down -v`.\n\n## Tested on real projects\n\nValidated **end-to-end inside the Docker toolbox** (engine + trivy + osv-scanner +\nsemgrep + gitleaks, all four scanners) on real, intentionally-vulnerable repos:\n\n| repo | lang | findings (taint + tools) | highlights |\n|------|------|--------------------------|------------|\n| [OWASP/NodeGoat](https://github.com/OWASP/NodeGoat) | JS | **275** — 13 taint · 262 tool (trivy 67, osv 163, semgrep 29, gitleaks 3) | the signature server-side **`eval()` SSJI** (`eval(req.body.…)`, CWE-94), **command injection**, **open redirects**, reflected **XSS** — plus dependency CVEs, hardcoded secrets (incl. a private key), and SAST findings |\n| [we45/Vulnerable-Flask-App](https://github.com/we45/Vulnerable-Flask-App) | Python | **206** — 6 taint · 200 tool (trivy 69, osv 110, semgrep 21) | **SQLi**, **insecure deserialization**, **path traversal**, **SSTI**, **weak crypto** (CWE-89/502/22/79/327) — plus Python dep CVEs and SAST |\n\nEvery finding's path is repo-relative and the grounding gate (`check`) passes over\nall of them; each is then adjudicated by the AI before it counts as confirmed.\nReproduce:\n\n```bash\nTARGET=/path/to/repo docker compose run --rm ultrasec scan --repo /work --out /work/.ultrasec\n```\n\n## How it works\n\n| stage | who | what |\n|-------|-----|------|\n| scan | engine | walk repo → cross-file/function link-graph (~15 langs) → enumerate candidate source→sink taint paths → run installed scanners → correlate across tools → EPSS/KEV/CVSS risk-rank → evidence packets |\n| adjudicate | **AI** | read the real code along each path; confirm reachability + exploitability; find authz/business-logic bugs the tools miss |\n| verify | **AI** + engine | adversarial worklist, conservative gate (uncertain high-severity → `needs-human`, never auto-dropped) |\n| report | engine | grounded, cited, tiered Markdown + self-contained HTML |\n\n## Development\n\n```bash\npnpm install\npnpm typecheck \u0026\u0026 pnpm test \u0026\u0026 pnpm run check:build   # the CI gate\n```\n\nReleases are automatic: Conventional Commits on `main` drive semantic-release\n(GitHub release + tarball).\n\n## License\n\nMIT\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxgfr%2Fultrasec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxgfr%2Fultrasec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxgfr%2Fultrasec/lists"}