Catch malicious packages before they ship.

Quick start by ecosystem

Same binary, native lockfile for your stack.

# install
go install github.com/qwexvf/aegis-cli/cmd/aegis@latest
# or download: https://github.com/qwexvf/aegis-cli/releases

# audit any node project
cd my-app
aegis ci .

# install gate wrapper (blocks risky deps at install time)
aegis npm install left-pad
aegis pnpm add react
aegis bun add zod
aegis yarn add lodash

# install
go install github.com/qwexvf/aegis-cli/cmd/aegis@latest

# poetry
cd my-py-app
aegis ci .                # reads poetry.lock

# uv
aegis ci .                # reads uv.lock

# pip-tools / requirements.txt
aegis ci --lockfile requirements.txt .

# inspect one package without installing
aegis analyze requests==2.31.0

# install
go install github.com/qwexvf/aegis-cli/cmd/aegis@latest

# audit Cargo.lock
cd my-rust-app
aegis ci .

# SBOM with dependency graph
aegis sbom . -o sbom.spdx.json

# inspect a crate
aegis analyze tokio@1.40.0

# install
go install github.com/qwexvf/aegis-cli/cmd/aegis@latest

# audit go.sum
cd my-go-svc
aegis ci .

# detect drift between releases
aegis snapshot save v1.0.0
go get -u ./...
aegis snapshot diff v1.0.0

# inspect a module
aegis analyze github.com/gin-gonic/gin@v1.10.0

# install
go install github.com/qwexvf/aegis-cli/cmd/aegis@latest

# audit Gemfile.lock
cd my-rails-app
aegis ci .

# inspect a gem
aegis analyze rails@7.1.0

# explain a finding
aegis explain nokogiri@1.16.0

Why another supply-chain scanner?

npm audit, pip-audit, and most SCA tools only check for known CVEs. They miss the entire class of attacks that defines modern supply-chain compromise: typosquats, install-hook payloads, obfuscated droppers, and compromised maintainer accounts. By the time a CVE exists, the package has already shipped.

Aegis adds two layers on top of OSV: AST-based capability detection that reads what the code actually does, and behavioral heuristics that flag the patterns malicious packages share. No machine learning hand-wave — just deterministic detectors you can read in the source.

What Aegis does

01 CVE & advisory lookup via OSV

Batched OSV.dev queries across npm, PyPI, RubyGems, crates.io, Go modules, and Maven. No API key. No rate limit. Findings include severity, fixed versions, and affected ranges.

02 AST capability scanning

Tree-sitter walks the actual source of every JS, Python, Ruby, Rust, and Go package. Flags network egress, child-process spawn, dynamic eval, filesystem write, and credential reads — even on packages with zero published advisories.

03 Behavior-based malware heuristics

Seven detectors target patterns nobody has indexed yet: lifecycle install hooks, base64/hex-obfuscated payloads, C2 URLs, binary droppers, typosquats against popular names, maintainer hijack, suspicious patch-version drift.

04 CI gate, drift, allowlist

aegis ci --fail-on=block returns nonzero on policy violations. Snapshot diffs surface new capabilities introduced between releases. YAML allowlists let you carve out known-good packages without disabling rules globally.

05 SPDX 2.3 SBOM with dependency graph

Generate signed SPDX 2.3 SBOMs with dependsOn[] relationships. Sigstore-compatible signing. Drop straight into supply-chain attestation pipelines.

06 GitHub Actions workflow scanning

Audit every .github/workflows/*.yml for pinned-by-tag references, third-party action drift, write-permissive tokens, and npm provenance verification.

Supported ecosystems

Aegis reads native lockfiles directly — no extra manifest, no annotation, no install step.

Examples

Real commands, real output. Copy, paste, run.

$ aegis ci .

  ◆ 312 packages · 14 ecosystems
  ◆ 2 critical · 5 high · 11 medium

  CVE-2024-XXXXX  axios@0.21.0    → 0.21.4
  install-hook    fake-pkg@1.0.0  net + child_process
  typosquat       expresss@4.18   → express

  exit 1

$ aegis explain fake-pkg@1.0.0

  capabilities:
    - net.egress        evidence: index.js:14 http.get(...)
    - child_process     evidence: postinstall.js:3 spawn('sh',...)
    - obfuscation       evidence: base64 payload > 4KB
  risk: BLOCK
  reason: install-hook + net + obfuscated payload

$ aegis sbom . -o sbom.spdx.json
  ✓ wrote 312 components, 408 relationships

$ aegis sbom . --sign --key cosign.key
  ✓ sigstore signature → sbom.spdx.json.sig

$ aegis snapshot save baseline
$ npm update
$ aegis snapshot diff baseline

  + lodash@4.17.21 → 4.17.22
      new capability: net.egress
  ⚠ unexpected drift in a patch release

$ aegis analyze lodash@4.17.21

  ecosystem:    npm
  size:         71 KB · 1042 LOC
  capabilities: -
  cve:          0 known
  risk:         OK

# aegis.allow.yml
packages:
  - name: esbuild
    version: ">=0.20.0"
    allow: [child_process]
    reason: native build, expected

$ aegis hook install
  ✓ .git/hooks/pre-commit installed

$ git commit -m "add dep"
  aegis: 1 new high-risk package — push blocked
  aegis explain <pkg> for details

$ aegis actions .

  release.yml
    actions/checkout@v4         unpinned (use SHA)
    third-party/spooky@main     unpinned + write:contents

$ aegis npm install left-pad
  ✓ left-pad@1.3.0 — OK
  → forwarding to npm install left-pad

$ aegis pnpm add suspicious-pkg
  ✗ install-hook + obfuscated payload
  → install aborted

$ aegis ci --format json . > findings.json
$ aegis ci --sarif aegis.sarif .
$ aegis ci --junit reports/aegis.xml .

# Pipe into anything
$ aegis ci --format json . | jq '.findings[].cve'

Attacks Aegis catches

Real public supply-chain incidents. Each one matched one or more Aegis detectors.

• event-stream

  npm · 2018

  Maintainer handoff to malicious actor → crypto-stealing payload injected.

  matched → maintainer drift · obfuscation · net.egress
• ua-parser-js

  npm · 2021

  Account hijack → install-hook downloaded coin miner + credential stealer.

  matched → install-hook · binary dropper · C2 URL
• colors.js / faker.js

  npm · 2022

  Author protest → infinite-loop sabotage shipped in a patch release.

  matched → snapshot drift · capability change in patch
• node-ipc

  npm · 2022

  Protestware patched in geo-targeted file-wiping logic.

  matched → fs.write to home dir · IP-based branching
• ctx + phpass

  PyPI / npm · 2023

  Squatted abandoned name → exfiltrated AWS env vars on import.

  matched → typosquat · credential read · net.egress on import
• xz-utils backdoor

  system / Go indirect · 2024

  Long-game maintainer trust → obfuscated build-time backdoor in liblzma.

  matched → obfuscation · maintainer drift · binary tamper
• lottie-player

  npm · 2024

  Maintainer phishing → wallet drainer injected via CDN-style npm release.

  matched → install-hook · obfuscation · C2 URL
• @solana/web3.js

  npm · 2024

  Compromised maintainer account → patch release stole private keys.

  matched → maintainer drift · credential read · capability change in patch

Aegis is deterministic — every detector is a readable function in the source. No ML, no hidden heuristics.

Drop into CI in 30 seconds

Single binary, exits nonzero on policy violations, emits SARIF for GitHub code scanning.

name: aegis
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with: { go-version: '1.22' }
      - run: go install github.com/qwexvf/aegis-cli/cmd/aegis@latest
      - run: aegis ci --fail-on=block --sarif aegis.sarif .
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with: { sarif_file: aegis.sarif }

Run aegis ci --fail-on=block --sarif aegis.sarif .

aegis 0.22.0 · go1.22.4 · linux/amd64

▸ parse lockfiles
  package-lock.json     1241 deps
  go.sum                  82 modules

▸ OSV lookup
  HTTP 200 · batched in 1 call · 38ms

▸ AST capability scan
  scanned 1323 packages · 4.1s

▸ heuristics
  ✓ install-hook
  ✓ obfuscation
  ✓ typosquat
  ✓ maintainer drift

▸ findings
  CVE-2024-21538  cross-spawn@7.0.3  → 7.0.6
  install-hook    fake-pkg@1.0.0     net + child_process
  typosquat       expresss@4.18      → express

▸ summary
  2 BLOCK · 3 WARN · 1318 OK
  SARIF written → aegis.sarif

##[error] aegis: policy violations
exit code 1

Frequently asked questions

Is Aegis free and open source?

Yes. The CLI is Apache-2.0 licensed and fully functional with no account. Aegis Cloud is a separate paid layer for sandbox dynamic analysis and team dashboards — the CLI does not require it.

Does Aegis send my code anywhere?

No. Static AST scanning, heuristics, and lockfile parsing all run locally. Only the OSV CVE lookup makes outbound HTTP calls — package names and versions, never source.

How is Aegis different from npm audit or pip-audit?

npm audit and pip-audit only look up known CVEs. Aegis adds AST-based capability detection and behavioral malware heuristics, catching malicious packages before they have a CVE assigned — the gap that 0-day supply-chain attacks exploit.

Which ecosystems are supported?

JavaScript/TypeScript (npm, pnpm, yarn), Python (Poetry, uv, pip), Ruby (Bundler), Rust (Cargo), and Go modules. Maven and NuGet CVE lookup via OSV; deeper AST coverage is planned.

Can I use Aegis in CI?

Yes — aegis ci is the dedicated CI entrypoint. It exits nonzero on policy violations, emits SARIF and JUnit XML, and runs in under a few seconds on typical lockfiles. GitHub Actions example in the docs.

Does Aegis generate SBOMs?

Yes. SPDX 2.3 with dependsOn[] dependency graph, optionally Sigstore-signed. Use aegis sbom <path> -o out.spdx.json.

OSS vs Aegis Cloud

CLI is fully functional with zero account. Cloud unlocks dynamic analysis + team features. Honest split.

• Getting started
• Cookbook
• Command reference
• Architecture