argus-radar 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shantanu Gopale
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# ARGUS · supply-chain radar
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![ci](https://github.com/shantanugopale/argus/actions/workflows/ci.yml/badge.svg)](https://github.com/shantanugopale/argus/actions/workflows/ci.yml)
+![node >= 22.13](https://img.shields.io/badge/node-%3E%3D22.13-green)
+![runtime deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen)
+![license](https://img.shields.io/badge/license-MIT-blue)
+
+<p align="center">
+  <img src="docs/img/dashboard.png" alt="Argus dashboard — viral repos + scan registry" width="900" />
+</p>
+
+Your dependencies change faster than you review them. Argus tracks **what's trending on npm and GitHub right now**, verifies whether it's **safe to install, right now**, and gives you one verdict — with the evidence chain, not just a score.
+
+```text
+verdict ▮▮▮▮▮▮▮▮▮▮  100/100 CRITICAL — do not install
+evidence
+◈ S10 Known vulnerabilities (+80)
+    OSV.dev lists 10 advisories for this package; worst severity CRITICAL: GHSA-29mw-wpgm-hmr9, …
+◈ S40 Bus-factor one (+20)
+    Only one maintainer (jdalton) for a package with 206,478,795 weekly downloads —
+    compromise of a single account redirects every consumer
+```
+
+**Zero runtime dependencies.** The radar itself is Node ≥ 22.13 with nothing installed — `node apps/cli/argus.ts` just runs (TypeScript via native type-stripping).
+
+**Live dashboard:** <https://shantanugopale.github.io/argus/> (static snapshot refreshed daily by CI, or run `node apps/api/main.ts` for live scanning).
+
+## Why
+
+Vibe-coders and LLM-driven dev loops install packages from trending pages and model suggestions within seconds. Existing gates (audit, socket, etc.) run *after* you've already adopted a dependency — and none of them look at *velocity*. Argus checks at the moment of install:
+
+- **Spot poisoning** — a familiar package whose daily downloads suddenly explode 8× over its own baseline
+- **Shocked-repo injection** — a repo that trends today with 1,000+ stars but is under 6 months old
+- **Classic malware** — install scripts, OSV advisories, typosquats against a built-in top-packages index
+
+## Quick start
+
+```bash
+# npm source of truth: Node >= 22.13 (native TS type-stripping, zero installs)
+node apps/cli/argus.ts scan chalk            # verdict + exit code 0/10/20
+node apps/cli/argus.ts trend                 # 14-day download-velocity radar + GitHub trending
+node apps/cli/argus.ts watch                 # daemon: rescan persisted refs every 15 min
+node apps/api/main.ts                        # dashboard on http://127.0.0.1:8787
+```
+
+### Scan any ref
+
+| ref | gate |
+| --- | --- |
+| `scan npm:lodash` | explicit npm package |
+| `scan lodash` | shorthand for `npm:` |
+| `scan gh:owner/repo` | GitHub repo incl. dependency-propagation (scans deps!) |
+| `scan chalk event-stream gh:octocat/Hello-World` | multiple refs, worst verdict wins |
+
+<p align="center">
+  <img src="docs/img/scan.png" alt="argus scan npm:lodash verdict" width="900" />
+</p>
+
+## The signals
+
+| id | signal | what it catches |
+| --- | --- | --- |
+| S10 | Known vulnerabilities | CVEs / malware advisories via OSV.dev |
+| S20 | Install scripts | `preinstall` / `postinstall` code execution surface |
+| S30 | Fresh-publish spike | brand-new release on a high-velocity package |
+| S40 | Bus-factor one | single maintainer holding millions of installs |
+| S60 | Typosquat | Levenshtein distance vs built-in top-packages index |
+| S70 | Version churn | too many releases in the last 21 days |
+| S80 | Repo linkage | missing source repository on a high-traffic package |
+| S90 | Repo trust basics | no license / no description on a repo |
+| S100 | Viral-no-history | trending today + young repo (24h GitHub pulse) |
+| S110 | Dep propagation | a gateway repo whose dependencies are risky on their own |
+
+The merge is **evidence over scores**: findings sum (clamped to 100), severity floors apply, and the `severe-cap invariant` guarantees a report with no severe finding can never cross into HIGH_RISK territory.
+
+## Exit codes (scriptable gates)
+
+| code | verdict |
+| --- | --- |
+| `0` | SAFE |
+| `10` | NEEDS_REVIEW |
+| `20` | HIGH_RISK / CRITICAL |
+| `3` | package/repo not found |
+| `5` | unexpected failure |
+
+Pipe it into CI: `node apps/cli/argus.ts scan chalk || exit 1`.
+
+## Architecture
+
+Hexagonal — pure engine, pluggable providers, thin front doors:
+
+```
+engine/          pure logic, fully hermetic · merge, signals, velocity, corpus analysis
+shell/           connectors (npm registry, OSV.dev, GitHub, npm downloads) + .argus/ persistence + fixture playback
+apps/cli         scan · trend · watch (exit-code contract)
+apps/api         loopback server: /api/scan · /api/trend · /api/scans · /healthz
+apps/web         zero-dependency static dashboard (served by apps/api)
+```
+
+- **Determinism:** `ARGUS_FIXTURES_DIR` replays recorded provider snapshots — CI never touches the network.
+- **Reproducibility:** every provider response is content-hashed and logged into the report.
+- **Persistence:** `.argus/scans/*.json` (digest-verified, 60 s TTL cache) + `.argus/trend/latest.json`.
+- **Tests:** 90+ (unit → integration → e2e incl. golden-corpus regression over 14 refs running through the full engine).
+- **Gates:** `npm run lint && npm run typecheck && npm test` (ubuntu + windows matrix CI).
+
+## Development
+
+```bash
+npm install                    # dev deps only (eslint + typescript)
+npm test                       # 90+ tests, hermetic
+npm run record                 # refresh fixture snapshots from live providers
+npm run api                    # start the dashboard
+```
+
+Docs: [`docs/01-PRD.md`](docs/01-PRD.md) · [`02-ARCHITECTURE.md`](docs/02-ARCHITECTURE.md) · [`03-THREAT-MODEL.md`](docs/03-THREAT-MODEL.md) · [`04-ADR.md`](docs/04-ADR.md) · [`05-SDLC-PLAN.md`](docs/05-SDLC-PLAN.md)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/apps/web/index.html

@@ -0,0 +1,138 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>ARGUS · supply-chain radar</title>
+<style>
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; }
+  body { background: #0b0f14; color: #d7e0ea; font-family: "Cascadia Code", Consolas, monospace; margin: 0; padding: 24px; }
+  h1 { font-size: 20px; letter-spacing: 2px; margin: 0 0 4px; }
+  .sub { color: #6b7a8c; font-size: 12px; margin-bottom: 24px; }
+  .panel { border: 1px solid #1d2733; border-radius: 10px; padding: 16px 18px; margin-bottom: 20px; background: #0e141b; }
+  h2 { font-size: 12px; letter-spacing: 1.5px; color: #8fb2d0; margin: 0 0 12px; text-transform: uppercase; }
+  table { width: 100%; border-collapse: collapse; font-size: 13px; }
+  td, th { padding: 6px 8px; border-bottom: 1px solid #16202b; text-align: left; }
+  th { color: #6b7a8c; font-weight: 400; font-size: 11px; letter-spacing: 1px; }
+  .spike-exploding { color: #ff6b6b; font-weight: bold; }
+  .spike-hot { color: #ffd166; }
+  .spike-rising { color: #d0a03b; }
+  .verdict-CRITICAL, .verdict-HIGH_RISK { color: #ff6b6b; }
+  .verdict-NEEDS_REVIEW { color: #ffd166; }
+  .verdict-SAFE { color: #7dd87d; }
+  .scanrow td:first-child { color: #7fd4f0; }
+  button { background: #14212e; color: #9fd2f5; border: 1px solid #1d3851; border-radius: 6px; padding: 8px 14px; font-family: inherit; cursor: pointer; }
+  button:hover { background: #1b2d3f; }
+  input { background: #0b1219; color: #d7e0ea; border: 1px solid #1d2733; border-radius: 6px; padding: 8px; font-family: inherit; width: 280px; }
+  code { color: #7fd4f0; }
+  footer { color: #45525f; font-size: 11px; margin-top: 30px; }
+  .empty { color: #55626e; font-size: 12px; }
+</style>
+</head>
+<body>
+<h1>ARGUS ▸ supply-chain radar</h1>
+<div class="sub">what's trending right now — and is it safe to install, right now · <code>exit codes 0/10/20</code></div>
+
+<div class="panel">
+  <h2>Scan a ref (npm package or gh:owner/repo)</h2>
+  <input id="ref" placeholder="chalk" />
+  <button onclick="scan()">scan</button>
+  <div id="scanArea" style="margin-top: 12px"></div>
+</div>
+
+<div class="panel">
+  <h2>Download spikes (top 15 npm cohort · 14d)</h2>
+  <div id="spikes" class="empty">loading…</div>
+</div>
+
+<div class="panel">
+  <h2>Viral GitHub repos (24h)</h2>
+  <div id="repos" class="empty">loading…</div>
+</div>
+
+<div class="panel">
+  <h2>Scan drill-down (registry reports persisted in .argus/)</h2>
+  <div id="history" class="empty">loading…</div>
+</div>
+
+<footer>ARGUS v1.0 · zero-dependency static client · evidence over scores</footer>
+
+<script>
+async function j(url, opts) {
+  const r = await fetch(url, opts);
+  if (!r.ok) throw new Error((await r.json().catch(() => ({}))).error || ("HTTP " + r.status));
+  return r.json();
+}
+
+let SNAPSHOT_MODE = false;
+async function withSnapshotFallback(apiUrl, key) {
+  try {
+    const r = await fetch(apiUrl);
+    if (r.ok) return await r.json();
+  } catch {}
+  SNAPSHOT_MODE = true;
+  const s = await fetch("snapshot.json", { cache: "no-store" }).then(r => r.ok ? r.json() : null).catch(() => null);
+  return s ? s[key] : null;
+}
+
+async function loadTrend() {
+  try {
+    const t = await withSnapshotFallback("/api/trend", "trend");
+    if (!t) throw new Error("no data");
+    if (SNAPSHOT_MODE) {
+      const sub = document.querySelector(".sub");
+      if (sub && !sub.dataset.tagged) { sub.textContent += " · static snapshot " + (t.generatedAt || ""); sub.dataset.tagged = "1"; }
+    }
+    const spikes = document.getElementById("spikes");
+    if (t.rows.length === 0) { spikes.innerHTML = '<span class="empty">no anomalous spikes in cohort</span>'; }
+    else {
+      spikes.innerHTML = "<table><tr><th>package</th><th>class</th><th>ratio</th><th>downloads/day</th><th></th></tr>" +
+        t.rows.slice(0, 12).map(r => "<tr><td><code>" + r.name + "</code></td><td class='spike-" + r.spike + "'>" + r.spike + "</td><td>" + r.burstRatio.toFixed(2) + "x" +
+          (r.cohortWide ? " (rel " + r.relativeRatio.toFixed(2) + "x)" : "") + "</td><td>" + r.latest.toLocaleString("en-US") + "</td>" +
+          "<td><button onclick=\"document.getElementById('ref').value='npm:" + r.name + "';scan()\">scan</button></td></tr>").join("") + "</table>";
+    }
+    const repos = document.getElementById("repos");
+    if (t.repos.length === 0) { repos.innerHTML = '<span class="empty">trending feed unavailable</span>'; }
+    else {
+      repos.innerHTML = "<table><tr><th>repo</th><th>★ today</th><th></th></tr>" +
+        t.repos.slice(0, 10).map(r => "<tr class='scanrow'><td><code>" + r.repo + "</code></td><td>" + r.starsThisPeriod.toLocaleString("en-US") + "</td>" +
+          "<td><button onclick=\"document.getElementById('ref').value='gh:" + r.repo + "';scan()\">scan</button></td></tr>").join("") + "</table>";
+    }
+  } catch (e) { document.getElementById("spikes").innerHTML = "error: " + e.message; }
+}
+
+async function scan() {
+  const ref = document.getElementById("ref").value.trim();
+  const area = document.getElementById("scanArea");
+  if (!ref) return;
+  area.innerHTML = "scanning " + ref + " …";
+  try {
+    const r = await j("/api/scan?ref=" + encodeURIComponent(ref));
+    const rows = r.findings.map(f => "<tr><td>" + f.id + "</td><td>" + f.title + "</td><td>+" + f.points + "</td><td class='verdict-" + r.verdict + "'>" + f.evidence + "</td></tr>").join("");
+    area.innerHTML =
+      "<div style='margin-bottom:8px'><span class='verdict-" + r.verdict + "' style='font-weight:bold'>" + r.verdict + "</span> · score " + r.score + "/100 · checked " + (r.persistedAt || r.checkedAt) + "</div>" +
+      (rows ? "<table><tr><th>sig</th><th>title</th><th>pts</th><th>evidence</th></tr>" + rows + "</table>" : "<span class='empty'>no signals fired — clean scan</span>");
+    loadHistory();
+  } catch (e) { area.innerHTML = "<span class='verdict-CRITICAL'>error: " + e.message + (SNAPSHOT_MODE ? " · static snapshot mode — run `node apps/api/main.ts` for live scans" : "") + "</span>"; }
+}
+
+async function loadHistory() {
+  try {
+    const items = await withSnapshotFallback("/api/scans", "scans");
+    if (!items) { document.getElementById("history").innerHTML = "<span class='empty'>no scans persisted yet — run one above</span>"; return; }
+    const el = document.getElementById("history");
+    if (items.length === 0) { el.innerHTML = "<span class='empty'>no scans persisted yet — run one above</span>"; return; }
+    el.innerHTML = "<table><tr><th>ref</th><th>verdict</th><th>score</th><th>persisted</th></tr>" +
+      items.slice(0, 12).map(i =>
+        "<tr class='scanrow'><td><code>" + i.ref + "</code></td><td class='verdict-" + i.verdict + "'>" + i.verdict +
+        "</td><td>" + i.score + "/100</td><td>" + new Date(i.persistedAt).toLocaleString("en-US") + "</td></tr>").join("") + "</table>";
+  } catch {}
+}
+
+document.getElementById("ref").addEventListener("keydown", e => { if (e.key === "Enter") scan(); });
+loadTrend();
+loadHistory();
+</script>
+</body>
+</html>

package/bin/cli.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// Argus launcher: bundled JS when installed from npm (node_modules forbids
+// type-stripping), raw TypeScript via Node's native stripping during dev.
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const bundled = join(here, "..", "dist", "npm", "cli.js");
+const devEntry = join(here, "..", "apps", "cli", "argus.ts");
+
+const [entry, needsStrip] = existsSync(bundled) ? [bundled, false] : [devEntry, true];
+const flags = needsStrip ? ["--experimental-strip-types"] : [];
+const result = spawnSync(process.execPath, [...flags, entry, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  env: process.env
+});
+process.exitCode = result.status ?? 1;