Configuration

How aegis is configured: environment variables, config file paths, and CI auto-detection. Authoritative as of the current main branch.

aegis is configured through three layers (CLI flags take precedence):

1. aegis.yml (or .aegis.yml) — project-level config at the repository root. Sets default flag values for aegis ci and aegis actions scan. Optional; missing file is silently ignored.
2. Environment variables — override built-in defaults globally.
3. CLI flags — highest precedence; always override config file and env vars.

This makes the binary safe to drop into shared CI runners without surprise state.

🌐 marks variables that are only meaningful when an Aegis API server is reachable. The hosted Aegis Cloud is not yet available today, so these can be left unset for local-only use.

Environment variables#

Core#

Override (audited bypass) 🌐#

These two only fire when the install gate is producing a block, which itself requires the Aegis API. Local-only commands don’t use them.

The override is the operator’s “I know what I’m doing” escape hatch. Both env vars must be set in the same invocation; the audit entry records the reason permanently. There is no global “always override” mode by design.

Caching#

Vulnerability lookup#

aegis snapshot enrich / aegis ci / aegis analyze cross-reference every dep against a vulnerability feed. The default backend is OSV.dev (Google) — public, free, no auth required. When AEGIS_API_KEY is set, the Aegis-managed feed (curated OSV + GHSA + npm advisories) is preferred and OSV is used as a fallback on transient errors. Both backends share the same usecase.VulnLookup interface.

Malware heuristics#

aegis snapshot enrich and aegis analyze run a chain of behavior-based malware detectors over every package source after the AST scanner finishes. The heuristics are language-agnostic where possible and catch zero-day patterns OSV doesn’t know about yet:

• Suspicious install hooks — curl|sh, inline node -e, base64-piped-to-shell, Pastebin/Discord/ngrok hosts. Covers npm package.json scripts and crates.io build.rs.
• Obfuscated payload — eval(atob(...)) (JS), eval(Net::HTTP.get(...)) (Ruby), exec(urlopen(...).read()) / exec(base64.b64decode(...)) (Python).
• Suspicious URL targets — Pastebin, Discord webhooks, Telegram bots, IP grabbers, IDN homoglyphs. Runs across .js / .ts / .py / .rb / .rs / .go source.
• Binary droppers — stray .exe/.dll/.so/.scpt/.ps1 in a package tarball. Per-ecosystem carve-outs recognise legitimate native shapes (PyPI <pkg>/.cpython-*-*.so, <pkg>/.libs/, .abi3.so, .pyd).
• Typosquat names — Levenshtein ≤ 2 from a curated top-list per ecosystem (npm, PyPI, crates.io). One-line addition per new ecosystem via top_<eco>_packages.txt.
• Maintainer hijack — fresh release after a long quiet period from a low-download package, the canonical event-stream / ctx / rest-client shape.
• Maintainer transfer — current version’s _npmUser differs from the previous version’s. Catches account-handoff attacks where the package is republished by a new (potentially attacker) maintainer.
• Tarball / source drift (opt-in) — fetches the GitHub repo tree for the tag matching the published version and diffs against the tarball file list. Flags scripts or code present in the tarball but absent from the source tag (the canonical “post-publish payload injection” shape).

Reachability#

aegis snapshot enrich walks your project’s source files and marks each dep as used, unused, or unknown depending on whether any import statement references it.

Registry#

Debugging#

Display / TTY#

CI auto-detection#

aegis decides whether it’s running in CI by looking at known marker variables. CI mode does two things: prompts auto-block (no waiting for stdin), and structured JSON logging is preferred over the pretty TTY format.

The full list of markers (any one being non-empty triggers CI mode):

If your CI system isn’t on this list, set CI=true or AEGIS_CI=1 explicitly.

Files and directories#

aegis writes only inside the user’s config / cache directories. It never writes to the project directory unless you explicitly aegis snapshot save (which writes ./aegis.lock) or aegis hook install (which writes .git/hooks/pre-commit).

Recommended .gitignore#

# user-level config (personal — never commit)
.aegis/

# project-level snapshot + allowlist — DO commit these:
# aegis.lock
# .aegis-allowlist.yaml

Allowlist YAML schema#

Both ~/.aegis/allowlist.yaml and ./.aegis-allowlist.yaml use the same schema:

version: 1
rules:
  - ecosystem: npm           # required: npm | pypi | crates | go | maven
    name: lodash             # required, "*" allowed for any
    version: "^4"            # optional (default "*")
    capability: dynamic-eval # optional (default "*")
    reason: "lodash._.template uses Function() to compile templates"

Strict decoding: unknown keys, unknown capabilities, and unsupported schema versions all error out. Run aegis allowlist verify to check both files before committing.

The org-allowlist file (~/.aegis/cache/org-allowlist.yaml) uses the same schema; it’s fetched from the API by aegis allowlist sync and applied as an extra layer between user and project rules.

Layering / precedence#

When a capability fires on (eco, name, version), the allowlist layers are evaluated in this order, specific names beating wildcards within each layer:

1. Builtin — internal/domain/builtin_allowlist.go (~20 hand-curated rules; cannot be edited)
2. User — ~/.aegis/allowlist.yaml
3. Org — ~/.aegis/cache/org-allowlist.yaml (only if aegis allowlist sync has run)
4. Project — ./.aegis-allowlist.yaml

If any layer suppresses a capability, the finding is annotated with the suppression source + reason but kept visible in --json output (so dashboards can still count “would-have-been-blocked-but-allowlisted” for transparency).

aegis.yml#

Place aegis.yml (or .aegis.yml) at the repository root to set default flag values for aegis ci and aegis actions scan. CLI flags always override config. Missing file is silently ignored.

# aegis.yml
version: 1

ci:
  fail_on: block          # --fail-on default (safe|review|prompt|block)
  scan_actions: true      # always run --scan-actions
  actions_fail_on: high   # --actions-fail-on default (low|medium|high|critical)
  sarif: false            # --sarif default
  no_enrich: false        # --no-enrich default

actions:
  fail_on: high           # --min-severity default for aegis actions scan
  repo: ""                # --repo default (owner/repo)

Precedence: CLI flag > aegis.yml > built-in default.

Invalid fail_on / actions_fail_on values error immediately at startup with a clear message — bad config never silently passes through to runtime.

See aegis.example.yml in the repository root for the full annotated reference.

Build-time configuration#

aegis is an all-in-one binary — no build-tag flavours. CGo (tree-sitter) is always linked in. ldflags injected at release time:

Surfaced by aegis version.