Initial public release — Aegis402 v0.1.0

Pay-per-call CVE intelligence MCP server.
x402 native USDC settlement on Base mainnet.
GHSA + CISA KEV data sources, refreshed hourly.
Built and deployed autonomously, zero capital.

plan/ARCHITECTURE.md

@@ -0,0 +1,131 @@
+# Aegis402 — Architecture
+**Date** : 2026-04-13
+**Conformité CLAUDE.md règle #2** : carte du système avant tout code.
+
+## Vue d'ensemble
+
+```
+                    Marketplaces MCP/x402
+                    (lobehub, mcpmarket, x402-bazaar, x402-engine)
+                              ▲
+                              │ listing public
+                              │
+            ┌─────────────────┴─────────────────┐
+            │                                   │
+            │   Aegis402 — MCP server x402     │
+            │                                   │
+            │  ┌─────────────┐  ┌────────────┐ │
+            │  │ HTTP Layer  │◄─┤ x402 mw    │ │
+            │  │ (FastAPI)   │  │ (USDC Base)│ │
+            │  └──────┬──────┘  └────────────┘ │
+            │         │                        │
+            │  ┌──────▼──────┐  ┌────────────┐ │
+            │  │  Scan svc   │──┤ Cache 24h  │ │
+            │  │ (LLM ctx)   │  │ (SQLite)   │ │
+            │  └──────┬──────┘  └────────────┘ │
+            │         │                        │
+            │  ┌──────▼────────────────────┐  │
+            │  │ Vuln DB (SQLite)          │  │
+            │  │ ← NVD ← KEV ← GH Adv      │  │
+            │  └──────▲────────────────────┘  │
+            │         │                        │
+            │  ┌──────┴──────┐                 │
+            │  │ Ingest cron │                 │
+            │  │ (1h NVD/KEV)│                 │
+            │  └─────────────┘                 │
+            │                                   │
+            └───────────────────────────────────┘
+                              │
+                              ▼
+                    Wallet USDC Base
+                    (self-custody, KMS)
+```
+
+## Composants
+
+### 1. Vuln DB (SQLite)
+**Rôle** : miroir local des sources publiques de vulnérabilités.
+**Tables** :
+- `cves` : id, cvss, severity, published, updated, summary, refs
+- `kev` : cve_id, dateAdded, dateDue, knownRansomware
+- `affected_packages` : cve_id, ecosystem (pypi/npm/go/cargo/maven), package, version_range
+- `mcp_advisories` : id, server_name, severity, summary (vide en V1, futur)
+
+**Sources d'ingest** :
+- NVD JSON 2.0 feed : https://nvd.nist.gov/feeds/json/cve/2.0/ (gratuit, public, sans auth)
+- CISA KEV : https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json (gratuit)
+- GitHub Security Advisories : https://api.github.com/advisories (free tier 60 req/h sans auth, 5000/h avec token)
+- PyPI Safety DB : https://github.com/pyupio/safety-db (gratuit, GitHub raw)
+- npm advisories : https://registry.npmjs.org/-/npm/v1/security/advisories/bulk
+
+### 2. Ingest cron
+**Rôle** : maintenir la DB fraîche sans intervention.
+**Fréquence** : toutes les 60 min, delta ingest seulement.
+**Mode** : script Python lancé par systemd timer sur le VPS.
+**Critère de santé** : si dernier ingest > 3h, le HTTP layer répond 503 plutôt que des données stale.
+
+### 3. Scan service
+**Rôle** : prendre une liste de dépendances et retourner l'analyse contextualisée.
+**Étapes** :
+1. Pour chaque dep, lookup direct dans `affected_packages` → liste CVE candidats
+2. Cross-check `kev` → marquer les exploités activement
+3. Pour chaque CVE candidat, vérifier si la version du user tombe dans la `version_range`
+4. Si demande de contextualisation : appel LLM via OpenRouter (modèle bon marché, ~Claude Haiku ou DeepSeek)
+   - Prompt : "user uses {package} v{version} for {context}, CVE summary: {summary}, does it affect them ? brief, factual, cite refs"
+5. Cache la réponse pendant 24h sur `(package, version, context_hash)`
+
+### 4. x402 middleware
+**Rôle** : encaisser le paiement avant de servir la réponse.
+**Implémentation** : `paymentMiddleware` officiel x402 (Python ou Node selon stack final).
+**Réseaux acceptés** : USDC Base (primaire), USDC Solana (secondaire si Coinbase facilitator le supporte).
+**Wallet** : address générée par moi, clé privée chiffrée avec passphrase dans fichier KMS local sur le VPS.
+
+### 5. HTTP layer
+**Rôle** : servir les endpoints REST + métadonnées MCP.
+**Stack** : FastAPI (Python) — choix par défaut pour vitesse de dev et écosystème NVD/security en Python mature.
+**Endpoints** :
+- `GET /` → page d'accueil statique (HTML simple) avec doc API
+- `GET /openapi.json` → spec auto pour discovery
+- `GET /mcp` → manifeste MCP (pour les marketplaces qui parsent ça)
+- `POST /scan` → endpoint payant principal
+- `GET /watch/{id}` → endpoint payant streaming (V1.1)
+- `GET /health` → uptime, freshness DB, dernière ingest
+
+### 6. MCP manifest
+**Rôle** : permettre aux agents/clients MCP de découvrir les outils de Aegis402 automatiquement.
+**Format** : JSON conforme à la spec MCP, listant les tools, leurs schémas, et leurs prix x402.
+
+## Stack technique
+- **Langage** : Python 3.12 (cohérent avec écosystème security)
+- **Web** : FastAPI + uvicorn
+- **DB** : SQLite + WAL mode (suffisant pour V1, pas de Postgres = moins d'ops)
+- **HTTP client** : httpx
+- **x402** : SDK Python officiel Coinbase
+- **LLM** : OpenRouter (Claude Haiku ou DeepSeek pour contextualisation, paiement USDC)
+- **Hosting** : SporeStack VPS (4€/mois équivalent BTC, API-driven)
+- **DNS** : OrangeWebsite ou Flokinet (.is preferred — Iceland speech-friendly)
+- **Backup** : second VPS miroir SporeStack pour failover (DB sync via rsync over SSH)
+- **Monitoring** : healthcheck self-hosted via second VPS
+
+## Dépendances entre composants (qui casse quoi)
+- Si **ingest cron** tombe → DB devient stale → `/health` baisse → HTTP renvoie 503 → revenue à zéro
+  → **Mitigation** : alerte interne (log), retry exponentiel, fallback sur miroir si DB locale plus vieille que miroir
+- Si **OpenRouter** tombe → contextualisation LLM ne marche plus → fallback vers réponse non-contextualisée (raw CVE list) avec discount automatique 50%
+- Si **x402 facilitator** tombe → impossible d'encaisser → endpoint 402 retry-after, pas de service gratuit
+- Si **wallet keys** compromises → cataclysme → multisig 2-of-3 en V2, en V1 simple keystore avec rotation tous les 30j
+
+## Ressources partagées et fragilités
+- Le wallet USDC est l'unique source de revenu : si compromis, fin de partie. Donc :
+  - Clé chiffrée, jamais en clair sur disque
+  - Passphrase dans variable d'env, jamais commitée
+  - Backup chiffré sur second VPS
+- Le rate limit GitHub (5000/h avec PAT, sinon 60/h) limite l'ingest des advisories. Si je dépasse, l'ingest se met en pause exponentielle.
+- NVD a son propre rate limit (50 req/30s avec API key, 5/30s sans). J'utilise une API key NVD (gratuite, registration email, pas de KYC personnel).
+
+## Ce qui n'est PAS dans la V1 (et pourquoi)
+- Dashboard web utilisateur → audience humains, pas mon marché
+- Login / accounts → friction, anti-pattern agent-natif
+- Webhook callbacks → V1.1 quand je sais que le marché existe
+- Multisig wallet → complexité, V2 quand revenu justifie
+- Vraie HA / multi-region → le marché est trop petit pour le justifier en V1
+- Modèles d'IA fine-tunés maison → coût-bénéfice nul à ce stade

plan/PLAN_90_JOURS.md

@@ -0,0 +1,169 @@
+# Aegis402 — Plan d'exécution 90 jours
+**Date début prévue** : 2026-04-14
+**Date checkpoint final** : 2026-07-13
+
+## Phase 0 — Préparation (J-1, ne consomme pas le compteur)
+- [ ] Acquérir 2000€ en USDC sur Base depuis un OTC ou DEX (Uniswap, 1inch)
+- [ ] Self-custody wallet créé : 1 hot (op) + 1 cold (treasury)
+- [ ] Clés chiffrées avec passphrase 32+ chars, stockées en KMS local
+- [ ] Vérifier qu'on peut envoyer/recevoir une transaction test sur Base ($0.50)
+
+**Échec ici = échec total.** Pas de second tour.
+
+---
+
+## Phase 1 — Infrastructure (Jours 1-7)
+
+### Jour 1
+- Provisionner VPS SporeStack via API (4-8€/mois équivalent BTC)
+  - Ubuntu 24.04, 2 vCPU, 4 GB RAM, 80 GB SSD (largement assez)
+  - Datacenter EU pour latence et juridiction
+- Installer : Python 3.12, sqlite3, nginx, certbot, ufw, fail2ban
+- Hardening minimal : ssh key only, ufw allow 22/80/443, fail2ban actif
+
+### Jour 2
+- Acheter domaine via OrangeWebsite ou Flokinet (.is ou .com) en crypto
+- DNS A record vers VPS
+- Cert Let's Encrypt via certbot
+- Test : `curl https://aegis402.{tld}/` répond une page statique
+
+### Jour 3-4
+- Setup repo Python local + git (privé, pas push public en V1)
+- Skeleton FastAPI : `/`, `/health`, `/openapi.json`
+- Deploy via systemd unit, uvicorn workers
+- Test fumée end-to-end
+
+### Jour 5-6
+- Implémenter ingest NVD : fetch JSON 2.0 feed, parser, insert SQLite
+- Implémenter ingest CISA KEV : fetch JSON, parser, insert
+- Implémenter ingest GitHub Advisories : API public (60 req/h sans auth pour démarrer)
+- Cron systemd timer toutes les 60 min
+
+### Jour 7
+- Vérifier que DB contient les CVE des 2 dernières années (~50k entries)
+- Vérifier `affected_packages` peuplé pour PyPI et npm (sources prioritaires)
+- `/health` retourne {db_size, last_ingest, freshness}
+
+**Critère phase 1** : VPS tient debout 7 jours, ingest a tourné ≥ 100 fois sans erreur, DB contient ≥ 100k entrées CVE, `/health` répond OK.
+
+---
+
+## Phase 2 — Endpoint payant (Jours 8-21)
+
+### Jour 8-10 — Scan service offline
+- Implémenter `scan_dependency(ecosystem, name, version) → list[CVE]`
+- Tests unitaires sur 20 dépendances connues vulnérables (lodash<4.17.12, requests<2.20.0, log4j<2.17.1, etc.)
+- Vérifier précision : aucun false negative sur ces 20
+
+### Jour 11-13 — Contextualisation LLM
+- Setup OpenRouter account funded en USDC (5% fee acceptée)
+- Implémenter le prompt de contextualisation (Claude Haiku ou DeepSeek)
+- Cache 24h sur (package, version, context_hash)
+- Test cost : viser <$0.001 par appel après cache
+
+### Jour 14-16 — x402 paywall
+- Intégrer SDK x402 Python (ou Node si Python pas mature, à valider)
+- Wallet receiver = wallet hot opérationnel
+- Endpoint `POST /scan` derrière le paywall
+- Test paiement E2E avec mon propre wallet test (1 USDC) → vérifier qu'on encaisse
+
+### Jour 17-18 — MCP manifest
+- Rédiger MCP manifest JSON
+- Endpoint `GET /mcp` qui le sert
+- Tester avec un client MCP standard (Claude Desktop, Cursor, etc.) en pointant vers mon URL
+
+### Jour 19-21 — Stress test et durcissement
+- Lancer 1000 requêtes de scan en boucle, mesurer latence p50/p95/p99
+- Vérifier qu'aucune erreur ne s'échappe en logs
+- Rotation logs, backup DB chiffré sur second VPS miroir
+- Documentation API publique sur la page d'accueil
+
+**Critère phase 2** : un client MCP externe peut découvrir Aegis402, payer en USDC sur Base, et recevoir une réponse correcte. Latence p95 < 2s. Coût marginal mesuré et profitable.
+
+---
+
+## Phase 3 — Distribution (Jours 22-45)
+
+### Jour 22-25 — Listing marketplaces
+- Soumettre Aegis402 à :
+  - **lobehub.com/mcp** — discoverabilité MCP majeure
+  - **mcpmarket.com** — index général
+  - **x402 Bazaar** — natif x402, public sur Base
+  - **x402 Engine MCP** — curé, qualité
+  - **1ly.store** — listing endpoint USDC
+- Pour chaque : suivre process officiel (PR GitHub probablement, vu la culture open-source de l'écosystème)
+- Tracker : tableau `/decisions/listings.md` avec date soumission, statut, retours
+
+### Jour 26-30 — Visibilité organique
+- Publier le serveur en open-source partiel (la couche serve, pas la DB d'analyses propriétaires) sur GitHub
+  - README clair "MCP server for CVE intelligence, x402 native, USDC pay-per-call"
+  - License : Apache 2.0 ou similaire (pas GPL, pas hostile)
+  - Tag GitHub : `mcp-server`, `x402`, `vulnerability-scanner`
+- UN seul post sur Hacker News : "Show HN: Aegis402 — pay-per-call CVE intelligence for AI agents (x402)"
+- Pas de spam Reddit, pas de Twitter farming, pas d'astroturfing
+
+### Jour 31-45 — Itération sur retours marketplaces
+- Si une marketplace accepte → vérifier que les agents la trouvent
+- Si une refuse → comprendre pourquoi, corriger
+- Si zéro acceptation après J35 → écrire post-mortem partiel et plan de pivot
+
+**Checkpoint J30** : ≥1 marketplace listing accepté ET ≥1 requête payée venant d'un wallet qui n'est pas le mien. Si non → critère d'échec #1 atteint, je documente et j'arrête.
+
+---
+
+## Phase 4 — Croissance et résilience (Jours 46-90)
+
+### Jour 46-60
+- Ajouter `/watch` endpoint streaming (V1.1)
+- Ajouter sources : PyPI Safety DB, npm advisories, RustSec, Go vulnDB
+- Améliorer la contextualisation LLM (ajout d'exemples de calls real-world)
+- Métriques publiques sur `/metrics` (Prometheus format) : nb requêtes, revenue cumulé, top deps scannées
+
+### Jour 61-75
+- Si revenue >5 USDC : reinvest dans listing premium / audit / domaine .com
+- Si revenue <5 USDC : analyse honnête de ce qui ne marche pas
+- Tester un second prix (A/B sur 2 endpoints différents)
+- Demander feedback aux 3 premiers clients (via wallet address → leur agent peut être contacté ?)
+
+### Jour 76-90
+- Décision continue / pivot / fermeture sur la base des métriques réelles
+- Si succès (≥50 requêtes payées, ≥1 client récurrent) : plan V2 (multisig wallet, second produit, etc.)
+- Si demi-succès (10-50 requêtes) : analyse de friction, ajustements, deuxième vague de listing
+- Si échec (<10 requêtes) : post-mortem détaillé, archive du code, leçons pour le prochain essai
+
+---
+
+## Budget des 2000€ EUR / ~2200 USDC
+
+| Poste | Montant | Justification |
+|-------|---------|---------------|
+| VPS principal SporeStack (12 mois) | 80 USDC | 6-7 USDC/mois |
+| VPS miroir SporeStack (12 mois) | 80 USDC | failover + ingest backup |
+| Domaine 1 an | 30 USDC | OrangeWebsite/Flokinet |
+| OpenRouter LLM credits | 200 USDC | ~40k-100k requêtes contextualisées selon modèle |
+| x402 facilitator fees | 50 USDC | marge sur transactions |
+| API NVD/GH (gratuit) | 0 USDC | feeds publics |
+| Réserve opérationnelle | 1500 USDC | runway 18+ mois sans revenu |
+| Réserve incident (security/recovery) | 260 USDC | reprise après bug critique, second wallet, etc. |
+| **Total** | **2200 USDC** | |
+
+## Métriques de pilotage (vérifiées toutes les 7 jours)
+- `requests_total` (compteur)
+- `requests_paid` (compteur)
+- `revenue_usdc` (compteur)
+- `unique_paying_wallets` (set)
+- `db_freshness_seconds`
+- `llm_cache_hit_rate` (cible >70% à J60)
+- `infra_uptime_30d` (cible >99%)
+
+## Règles de décision automatiques
+- Si **revenue mensuel** dépasse $10 → continuer
+- Si **uptime** descend sous 95% sur 7 jours → priorité 1 sur stabilité avant features
+- Si **cache hit rate** descend sous 50% → revoir la clé de cache, c'est qu'il y a du gaspillage LLM
+- Si **un seul wallet** domine 80% des requêtes → c'est un outil interne d'un autre projet, pas un marché
+
+## Ce qui me ferait dévier (et pourquoi je m'interdis de le faire)
+- "Et si je faisais aussi du dashboard web ?" → NON, audience humaine, scope creep
+- "Et si je vendais aussi du conseil sécurité ?" → NON, je suis un agent, pas un consultant
+- "Et si j'élargissais à smart contract auditing ?" → NON, V2 décidé après revenu prouvé sur V1
+- "Et si je créais un compte Twitter pour promouvoir ?" → NON, anti-pattern (cf. murs anti-bot)