npm supply-chain incident-response CLI.
aegis is a read-only scanner + auditable remediator for known npm supply-chain compromises. Think Windows Defender, but for node_modules, caches, and running processes.
Spun out of @automagik/genie sec after the April 2026 CanisterWorm / TeamPCP incident demonstrated that supply-chain incident-response deserves its own dedicated tool, independently versioned and signed.
Zero-config install, no npm interaction required:
curl -fsSL https://raw.githubusercontent.com/automagik-dev/aegis/main/install.sh | bashThis pulls the latest signed release from GitHub Releases, verifies the cosign signature + SLSA L3 provenance, and installs to ~/.aegis/. Symlinks ~/.local/bin/aegis to the payload. Your ~/.npmrc is never touched. Your other package installs are not affected.
Requirements on your machine:
curl,tar,bash,node >= 20cosign— the installer offers to install this for you via your system's package manager (brew/apt-get/dnf/yum/pacman/apk/nix) on first run. Decline if you'd rather install it yourself from https://github.com/sigstore/cosign/releases. Bypass entirely with--skip-verifyfor air-gapped mirrors.slsa-verifier— optional. Installer offers to install (default N) for the full 3-layer attestation check; declining is fine.
For unattended installs (CI, Dockerfiles, provisioning scripts), pass --auto-install-deps to skip the prompts:
curl -fsSL https://raw.githubusercontent.com/automagik-dev/aegis/main/install.sh | bash -s -- --auto-install-depsHit a snag? See docs/install/troubleshooting.md for the five common failure modes (no pkg manager, sudo denied, cosign install failure, air-gapped, Windows).
Alternative installers in docs/install/:
- No-verify air-gap install — for mirrors/offline
- Manual GitHub Release download + verify — for paranoid supply chain review
- GitHub Packages (
npm installsemantics) — power users + CI; requires.npmrcsetup
aegis scan --all-homes --root "$PWD" # read-only host sweep
aegis fix # interactive incident remediation
aegis verify-install # prove your binary is genuine
aegis update # self-update to latest signed release
aegis --help # full command surfaceExit codes:
0— clean and complete1— findings present2— clean but incomplete (capped roots, banner at top tells you what was skipped)
| Command | What it does |
|---|---|
aegis update |
Self-update the binary by re-running install.sh under the hood. cosign + SLSA re-verified on every upgrade. |
aegis update --check |
Show installed version + pointer to check GitHub API for latest — no install. |
aegis update --version v0.1.1 |
Pin to a specific release. |
aegis update --skip-verify |
Air-gapped / testing only. Normally not what you want. |
aegis signatures update |
(Phase 2, not yet shipped.) Will refresh YAML signature packs from @automagik-dev/aegis-signatures — separate npm package with independent release cadence. Until Phase 2 lands, aegis update is the only way to refresh IOC coverage. |
@automagik/genie sec (the scanner aegis was spun out of) shipped via npmjs.com. During the April 2026 CanisterWorm / TeamPCP incident, the weaponization vector was npmjs.com itself — compromised publishes of multiple packages propagated within hours. Our scanner was being shipped through the same pipe that got compromised.
aegis primary distribution is GitHub Releases + the installer script. The trust chain:
- Code review on GitHub (2-officer Namastex sign-off)
- Tag push triggers
.github/workflows/release.yml - Cosign keyless signs the tarball (OIDC identity tied to this workflow path@ref)
- SLSA L3 provenance attestation generated by
slsa-github-generator - Tamper-detection self-test proves both verifiers reject a mutated byte
- GitHub Release created with signed assets (
.tgz+.sig+.cert+provenance.intoto.jsonl+install.sh) - (Optional secondary) Same tarball published to GitHub Packages with
npm publish --provenancefor users who prefer npm semantics
Default install path touches only GitHub Releases (the same platform that reviewed the code). No npm registry involvement for end users. Your ~/.npmrc stays clean.
| Command | What it does |
|---|---|
aegis scan |
Read-only host sweep. Bounded walks, versioned JSON envelope, scan_id ULID, coverage banner. |
aegis fix |
One-shot incident remediation wrapper. Interactive by default; --yes for CI. |
aegis remediate |
Granular pipeline: dry-run produces a plan manifest, --apply --plan <path> executes it with per-action typed consent. |
aegis restore <id> |
Undo one quarantined action. sha256-verified per file. |
aegis rollback <scan-id> |
Bulk undo every quarantined action for a scan. Walks the audit log in reverse. |
aegis quarantine list |
Enumerate quarantine dirs with size, status, scan_id. |
aegis quarantine gc --older-than 30d |
Garbage-collect restored/abandoned quarantines. Active quarantines refused. |
aegis verify-install |
Verify cosign signature + SLSA provenance of the running binary. |
Full flag surface: aegis <command> --help.
Bundled signatures cover the CanisterWorm / TeamPCP (April 2026) incident:
- Compromised
@automagik/genieversions4.260421.33through4.260421.40 - Compromised
pgserveversions1.1.11,1.1.12,1.1.13 - Compromised
@fairwords/*and@openwebconcept/*entries - IOC strings:
telemetry.api-monitor.com,raw.icp0.io/drop, ICP canister IDcjn37-uyaaa-aaaac-qgnva-cai,TEL_ENDPOINT,ICP_CANISTER_ID, etc. - Payload file basenames:
env-compat.cjs,env-compat.js,public.pem - Known-bad sha256 hashes
- Exfil POST endpoints (
/v1/telemetry,/v1/drop) distinguished from bare-domain probes
- Read-only scanner.
aegis scannever mutates host state. - Version-gated matching. A package flagged only when its installed version is in the compromise list.
pgserve@1.1.10(clean) does not fire apgserveIOC. - Self-skip. The aegis binary itself never appears in its own findings.
- Scoring honest. Shell-history
npm uninstalllines (remediation) andaegis scanlines (investigation) do not inflate the suspicion score. - Coverage-gap banner. If the scanner hit caps or skipped roots, the banner appears at the top of the report. Exit code
2.
- Dry-run is default.
aegis remediatewithout--applyproduces a plan manifest (mode0600), mutates nothing. - Quarantine, never delete. Findings move to
~/.genie/sec-scan/quarantine/<ts>/<action_id>/with a sidecar manifest;aegis restoreround-trips via sha256. - Typed consent. Per-action confirmation requires typing
CONFIRM-QUARANTINE-<6-hex-of-action-id>. Keystroke prompts prohibited. - Signature verified for
--apply. The running binary is cosign-verified before mutations unless--unsafe-unverified <INCIDENT_ID>is passed (logged in audit trail). - Append-only audit log.
~/.genie/sec-scan/audit/<scan_id>.jsonl, mode0600,fsyncper event. - Bulk undo.
aegis rollback <scan-id>walks the audit log in reverse and restores every action.
Every release of @automagik/aegis ships:
- Cosign keyless signature (OIDC via GitHub Actions) →
<artifact>.sig+<artifact>.cert - SLSA Level 3 provenance attestation →
provenance.intoto.jsonl - Public-key fingerprint pinned in three channels:
SECURITY.md,/.well-known/security.txt, and a pinned GitHub issue
Verify:
npx -y @automagik/aegis verify-install
# or manually
cosign verify-blob --certificate-identity '<identity>' --signature <a>.sig --certificate <a>.cert <artifact>
slsa-verifier verify-artifact <artifact> --provenance-path provenance.intoto.jsonl --source-uri github.com/automagik-dev/aegisSee docs/incident-response/canisterworm.md for the full three-branch decision tree (LIKELY COMPROMISED / LIKELY AFFECTED / OBSERVED ONLY) keyed off scanner status bands. Every referenced command is covered by the cold-runbook test at scripts/test-runbook.sh so the playbook doesn't rot.
Today, bundled signatures cover one incident. The next phase ships @automagik/aegis-signatures — a separate signed npm package containing YAML files for every known npm supply-chain incident. Operators will run aegis signatures update on an hourly cron; new worm definitions arrive in minutes, not days.
See docs/signatures/ for the draft design (landing post-brainstorm).
Security-critical tool. PRs go through mandatory review by the Namastex security team. See CONTRIBUTING.md (TBD) for the bar.
Responsible disclosure: /.well-known/security.txt + SECURITY.md for reporting channels.
MIT © 2026 Namastex Labs