aimarket-momus 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. aimarket_momus-0.1.0/.gitignore +16 -0
  2. aimarket_momus-0.1.0/LICENSE +21 -0
  3. aimarket_momus-0.1.0/PKG-INFO +379 -0
  4. aimarket_momus-0.1.0/README.md +364 -0
  5. aimarket_momus-0.1.0/momus/__init__.py +20 -0
  6. aimarket_momus-0.1.0/momus/a2a.py +171 -0
  7. aimarket_momus-0.1.0/momus/app.py +638 -0
  8. aimarket_momus-0.1.0/momus/bounty.py +65 -0
  9. aimarket_momus-0.1.0/momus/budget.py +185 -0
  10. aimarket_momus-0.1.0/momus/bulletin.py +990 -0
  11. aimarket_momus-0.1.0/momus/capabilities.py +598 -0
  12. aimarket_momus-0.1.0/momus/config.py +132 -0
  13. aimarket_momus-0.1.0/momus/economics.py +668 -0
  14. aimarket_momus-0.1.0/momus/engine/__init__.py +6 -0
  15. aimarket_momus-0.1.0/momus/engine/remediation.py +142 -0
  16. aimarket_momus-0.1.0/momus/engine/scanner.py +175 -0
  17. aimarket_momus-0.1.0/momus/engine/selfaudit.py +149 -0
  18. aimarket_momus-0.1.0/momus/engine/verify.py +112 -0
  19. aimarket_momus-0.1.0/momus/findings.py +220 -0
  20. aimarket_momus-0.1.0/momus/intel/__init__.py +38 -0
  21. aimarket_momus-0.1.0/momus/intel/cards.py +74 -0
  22. aimarket_momus-0.1.0/momus/intel/distill.py +143 -0
  23. aimarket_momus-0.1.0/momus/intel/sources.py +147 -0
  24. aimarket_momus-0.1.0/momus/intel/store.py +220 -0
  25. aimarket_momus-0.1.0/momus/main.py +24 -0
  26. aimarket_momus-0.1.0/momus/providers.py +424 -0
  27. aimarket_momus-0.1.0/momus/security.py +131 -0
  28. aimarket_momus-0.1.0/momus/settlement.py +202 -0
  29. aimarket_momus-0.1.0/momus/store.py +415 -0
  30. aimarket_momus-0.1.0/momus/targets/__init__.py +43 -0
  31. aimarket_momus-0.1.0/momus/targets/base.py +125 -0
  32. aimarket_momus-0.1.0/momus/targets/hub.py +85 -0
  33. aimarket_momus-0.1.0/momus/targets/injection.py +104 -0
  34. aimarket_momus-0.1.0/momus/targets/oracle.py +367 -0
  35. aimarket_momus-0.1.0/momus/vault.py +202 -0
  36. aimarket_momus-0.1.0/momus/warden_feed.py +376 -0
  37. aimarket_momus-0.1.0/momus/warden_reports.py +310 -0
  38. aimarket_momus-0.1.0/pyproject.toml +37 -0
  39. aimarket_momus-0.1.0/tests/conftest.py +91 -0
  40. aimarket_momus-0.1.0/tests/test_audit_fixes.py +450 -0
  41. aimarket_momus-0.1.0/tests/test_bulletin.py +600 -0
  42. aimarket_momus-0.1.0/tests/test_bulletin_disclosure.py +316 -0
  43. aimarket_momus-0.1.0/tests/test_bulletin_routes.py +329 -0
  44. aimarket_momus-0.1.0/tests/test_control_gate.py +108 -0
  45. aimarket_momus-0.1.0/tests/test_economics.py +243 -0
  46. aimarket_momus-0.1.0/tests/test_findings_and_security.py +71 -0
  47. aimarket_momus-0.1.0/tests/test_providers.py +77 -0
  48. aimarket_momus-0.1.0/tests/test_remediation_a2a.py +156 -0
  49. aimarket_momus-0.1.0/tests/test_scan_and_intel.py +163 -0
  50. aimarket_momus-0.1.0/tests/test_selfaudit_and_app.py +118 -0
  51. aimarket_momus-0.1.0/tests/test_settlement.py +130 -0
  52. aimarket_momus-0.1.0/tests/test_store.py +123 -0
  53. aimarket_momus-0.1.0/tests/test_vault_budget.py +208 -0
  54. aimarket_momus-0.1.0/tests/test_warden_feed.py +343 -0
  55. aimarket_momus-0.1.0/tests/test_warden_reports.py +359 -0
@@ -0,0 +1,16 @@
1
+ data/
2
+ *.key
3
+ *_signing_key
4
+ .venv/
5
+ __pycache__/
6
+ *.pyc
7
+ .pytest_cache/
8
+ .coverage
9
+ coverage/
10
+ htmlcov/
11
+ frontend/node_modules/
12
+ frontend/dist/
13
+ *.egg-info/
14
+ dist/
15
+ build/
16
+ .DS_Store
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 AI-Factory Project Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,379 @@
1
+ Metadata-Version: 2.4
2
+ Name: aimarket-momus
3
+ Version: 0.1.0
4
+ Summary: MOMUS — autonomous adversarial-audit (red team) satellite: safe conformance probes against the ecosystem's own components, signed findings, and a payer-separated bounty ledger
5
+ License-File: LICENSE
6
+ Requires-Python: >=3.11
7
+ Requires-Dist: aimarket-oracle-core>=0.2
8
+ Requires-Dist: httpx>=0.27.0
9
+ Provides-Extra: dev
10
+ Requires-Dist: httpx>=0.27.0; extra == 'dev'
11
+ Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
12
+ Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
13
+ Requires-Dist: pytest>=8.3.0; extra == 'dev'
14
+ Description-Content-Type: text/markdown
15
+
16
+ # MOMUS
17
+
18
+ <!-- aicom-readme-badges -->
19
+ <p align="center">
20
+ <a href="https://github.com/alexar76/momus/actions/workflows/ci.yml"><img src="docs/badges/ci.svg" alt="CI" /></a>
21
+ <a href="https://momus.modelmarket.dev/"><img src="docs/badges/live.svg" alt="Live panel" /></a>
22
+ <a href="https://alexar76.github.io/momus/"><img src="docs/badges/landing.svg" alt="Landing" /></a>
23
+ <a href="https://pypi.org/project/aimarket-momus/"><img src="docs/badges/pypi.svg" alt="PyPI" /></a>
24
+ <img src="docs/badges/tests.svg" alt="171 tests passed" />
25
+ <img src="docs/badges/python.svg" alt="Python >=3.11" />
26
+ <img src="docs/badges/docker.svg" alt="Docker ready" />
27
+ <img src="docs/badges/deepseek.svg" alt="DeepSeek default" />
28
+ <img src="docs/badges/signed.svg" alt="Ed25519-signed findings" />
29
+ <img src="docs/badges/a2a.svg" alt="A2A peer" />
30
+ <a href="https://github.com/alexar76/treasury"><img src="docs/badges/treasury.svg" alt="Separate payer key" /></a>
31
+ <a href="https://github.com/alexar76/momus/blob/main/LICENSE"><img src="docs/badges/license.svg" alt="License: MIT" /></a>
32
+ </p>
33
+ <!-- /aicom-readme-badges -->
34
+
35
+ <p align="center">
36
+ <a href="https://momus.modelmarket.dev/">
37
+ <img src="docs/screenshots/readme/hero.png" alt="MOMUS — the unblinking eye, scanning and signing" width="860">
38
+ </a>
39
+ <br>
40
+ <sub><b>The auditor that finds the flaw and signs the evidence.</b> — <a href="https://momus.modelmarket.dev/"><b>live panel →</b></a> · <a href="https://alexar76.github.io/momus/"><b>landing →</b></a> · <a href="#run-it"><b>run locally →</b></a></sub>
41
+ </p>
42
+
43
+ <p align="center">
44
+ <strong>MOMUS</strong> — the ecosystem's <strong>red team</strong>, living in its own house<br/>
45
+ Finds the flaw · <strong>signs</strong> the evidence · <strong>cannot pay itself</strong> · feeds the <a href="https://github.com/alexar76/argus">blue team</a>
46
+ </p>
47
+
48
+ <p align="center">
49
+ <strong><a href="https://momus.modelmarket.dev/">Live panel</a></strong>
50
+ ·
51
+ <strong><a href="docs/warden-channel.md">MOMUS → WARDEN channel</a></strong>
52
+ ·
53
+ <strong><a href="docs/found-and-fixed.md">Bugs actually found & fixed</a></strong>
54
+ ·
55
+ <strong><a href="docs/first-cycle.md">The first live cycle</a></strong>
56
+ ·
57
+ <strong><a href="docs/uni-chain.md">Every transaction explained</a></strong>
58
+ ·
59
+ <strong><a href="https://github.com/alexar76/treasury">Treasury</a></strong>
60
+ </p>
61
+
62
+ > 🌐 **English** · [Русский](README.ru.md) · [Español](README.es.md) · [Français](README.fr.md) · [中文](README.zh.md)
63
+
64
+ > **Momus** (Μῶμος), the Greek daimon of blame, judged Hephaestus's man and faulted him for one
65
+ > thing: no **window in the chest** through which his thoughts could be inspected. That is the
66
+ > oldest argument for auditability — a system you cannot see into cannot be trusted. MOMUS is that
67
+ > window for the AI-economy. It is the **offensive** complement to [ARGUS](https://github.com/alexar76/argus)'s
68
+ > defensive WARDEN: a tolerated adversary, living in our own house, whose only job is to find the flaw
69
+ > and **sign the evidence**.
70
+
71
+ MOMUS runs **safe, read-only** conformance/adversarial probes against the ecosystem's **own**
72
+ components — oracle free-tier ceilings, manifest/receipt signatures, settlement gates,
73
+ prompt-injection surfaces — and emits **Ed25519-signed findings** anyone can verify offline. It
74
+ sells scans on the marketplace like any satellite (the `oracle-core` AIMarket v2 surface), it
75
+ learns which attacks pay off, and — the property that matters most — **it finds and signs, but it
76
+ cannot pay itself.** A separate **Treasury** role (its own key, its own container) is the only
77
+ thing that can release a bounty, and only on independent verification.
78
+
79
+ - **Backend port:** `9400` (`9410` in prod — `:9400` there belongs to the oracle family) · **Treasury:** `9401`/`9411` · **Frontend:** `5186`
80
+ - **Live:** [momus.modelmarket.dev](https://momus.modelmarket.dev/) on the oracle host · **PyPI:** `aimarket-momus`
81
+ - **Default LLM:** DeepSeek V4 Pro (remote API — no heavy local model on a modest box)
82
+
83
+ ## Gallery
84
+
85
+ <p align="center">
86
+ <img src="docs/screenshots/readme/panel.png" alt="MOMUS live panel — findings, key separation, self-learning" width="860"><br>
87
+ <sub>Live panel · signed findings · the key-separation proof · probe priorities the bandit learned</sub>
88
+ </p>
89
+
90
+ <p align="center">
91
+ <img src="docs/screenshots/readme/monitor.png" alt="MOMUS and Treasury as nodes in the Alien Monitor" width="860"><br>
92
+ <sub>MOMUS and Treasury as their own nodes in the <a href="https://magic-ai-factory.com/monitor/">Alien Monitor</a> — click either for its live panel</sub>
93
+ </p>
94
+
95
+ ## What makes it not-a-scanner
96
+
97
+ | | |
98
+ |---|---|
99
+ | 🔴 **Finds and signs, cannot pay** | The scanner key never releases money. A separately-keyed [Treasury](https://github.com/alexar76/treasury) pays, and only on **independent** verification — HIGH severity needs two distinct verifiers, one of them external. |
100
+ | 🧭 **Honest outcomes** | `FINDING` / `NO_FINDING` / **`INCONCLUSIVE`**. An unreachable target is neither a finding nor a pass — a red team that cries wolf is worth nothing, and [one such false positive](docs/found-and-fixed.md) is documented. |
101
+ | 🔧 **A fix loop, not a report** | A confirmed finding becomes an A2A ticket to SKOPOS, which drives the Factory to patch it, asks MOMUS to re-test as the **deploy gate**, then signs a DeployOrder a node agent claims and verifies locally. |
102
+ | 🛡 **Feeds the blue team** | Confirmed third-party findings are published as a signed feed [ARGUS's WARDEN firewall](docs/warden-channel.md) already knows how to verify — accepted on production by **ARGUS's own verifier**. |
103
+ | 📚 **Self-learning** | A UCB1 bandit over per-(attack-class, target-kind) Beta posteriors, plus external advisories as a recency-decayed prior. It gets better at guessing where to look. |
104
+ | 🧾 **Its own corpus** | Every finding persists (SQLite by default, Postgres on a DSN) with a **deterministic** dedup identity, so one bug is never paid twice and a rediscovery bumps `seen_count`. |
105
+
106
+ ---
107
+
108
+ ## How MOMUS works
109
+
110
+ ```mermaid
111
+ flowchart LR
112
+ subgraph MOMUS["MOMUS · scanner key only"]
113
+ ENG[Scan engine]
114
+ STR[(Self-learning<br/>UCB bandit)]
115
+ INTEL[[Threat intel<br/>CISA / OSV / GHSA]]
116
+ end
117
+ TARGETS[/"Allowlisted targets<br/>oracles · hub · metis · gaia"/]
118
+ METIS{{Metis<br/>independent verifier + cognition}}
119
+ TREAS["Treasury · treasury key only"]
120
+ ESCROW[(Pay-on-Verified escrow)]
121
+
122
+ INTEL -- distilled cards --> STR
123
+ STR -- probe priority + seeds --> ENG
124
+ ENG -- safe read-only probes --> TARGETS
125
+ TARGETS -- responses --> ENG
126
+ ENG -- signed Finding --> METIS
127
+ METIS -- signed Verdict --> TREAS
128
+ ENG -- Finding + Verdicts --> TREAS
129
+ TREAS -- releases bounty --> ESCROW
130
+ ENG -. outcomes .-> STR
131
+
132
+ classDef pay fill:#2a0e12,stroke:#ff2d55,color:#fff;
133
+ class TREAS,ESCROW pay;
134
+ ```
135
+
136
+ MOMUS submits; the Treasury pays. The two boxes never share a key — that is the whole design.
137
+
138
+ ### The scan → verify → pay lifecycle
139
+
140
+ ```mermaid
141
+ sequenceDiagram
142
+ autonumber
143
+ participant S as MOMUS (scanner key)
144
+ participant T as Target (own contract)
145
+ participant V as Independent verifier(s)<br/>Metis + a 2nd key
146
+ participant Tr as Treasury (treasury key)
147
+ participant E as Escrow
148
+
149
+ S->>T: safe probe (over-ceiling unpaid, tamper sig, injection canary…)
150
+ T-->>S: response
151
+ S->>S: classify → sign Finding (Ed25519)
152
+ S->>V: request verification
153
+ V-->>S: signed Verdict (confirmed / refuted)
154
+ S->>Tr: Finding + Verdicts + deposit
155
+ Tr->>Tr: re-verify EVERY signature itself
156
+ Tr->>Tr: quorum? distinct keys? external present? dedup? deposit? crypto on?
157
+ alt all gates pass
158
+ Tr->>E: release bounty (treasury-signed)
159
+ Tr-->>S: PAID
160
+ else any gate fails
161
+ Tr-->>S: REFUSED / HELD (fail-closed) + reasons
162
+ end
163
+ ```
164
+
165
+ ### Who pays — the separation of duties
166
+
167
+ No single key both declares a finding valid **and** releases its payout.
168
+
169
+ ```mermaid
170
+ flowchart TB
171
+ subgraph roles[" "]
172
+ direction LR
173
+ SC["🔎 Scanner (MOMUS)<br/>probe · sign Finding<br/>❌ cannot pay"]
174
+ VE["⚖️ Verifier(s)<br/>sign Verdict<br/>❌ cannot pay"]
175
+ TR["🏦 Treasury<br/>release bounty<br/>❌ cannot find/verify"]
176
+ end
177
+ SC -- Finding --> TR
178
+ VE -- Verdict --> TR
179
+ TR -- "≥2 distinct keys · ≥1 external · dedup · deposit · fail-closed" --> PAY([💸 bounty released])
180
+
181
+ note["KEY BOUNDARY: scanner key ≠ verifier key ≠ treasury key.<br/>The Treasury refuses to start if scanner == treasury."]
182
+ TR -.-> note
183
+ ```
184
+
185
+ | Severity | Bounty | Deposit (anti-griefing) | Distinct verifiers | External verifier required |
186
+ |----------|--------|-------------------------|--------------------|----------------------------|
187
+ | info | — (never pays) | — | — | — |
188
+ | low | $2 | 25% | 1 | no |
189
+ | medium | $10 | 25% | 1 | no |
190
+ | high | $50 | 50% | **2** | **yes** (e.g. Metis) |
191
+ | critical | $200 | 50% | **2** | **yes** |
192
+
193
+ Guarantees, all enforced in code and covered by tests:
194
+ - **Scanner can't self-verify** — a verdict signed by the scanner key never counts.
195
+ - **Distinct did:keys ≠ distinct parties** — high/critical need ≥1 confirmation from a *registered
196
+ external* verifier; small-order/forged Ed25519 keys are rejected (AWR §6.3).
197
+ - **No double pay** — a bug's dedup key pays once, ever.
198
+ - **Spam costs money** — a refuted claim forfeits its whole deposit.
199
+ - **Infra is never auto-paid** — a finding against MOMUS/Treasury/verifier routes to human review.
200
+ - **Fail-closed** — crypto off → HELD intent, not released; no treasury key → refused; prod without
201
+ an external verifier → refused.
202
+
203
+ ### Splitting the bounty across the pipeline
204
+
205
+ A bug isn't *found* into value — it's found → fixed → deployed. So the bounty is a **pool split
206
+ across the verified contributors**, and the **Treasury releases every share**, each gated on an
207
+ *objective signed signal* — nobody grades or pays their own work:
208
+
209
+ | Subject | Share | Released when (signed evidence) |
210
+ |---------|-------|---------------------------------|
211
+ | **MOMUS** (finder) | 50% | the finding is independently confirmed |
212
+ | **AI-Factory** (fixer) | 35% | MOMUS's signed `fixed` re-test verdict |
213
+ | **SKOPOS** (conductor) | 15% | job DONE: fixed verdict **+** deploy ack |
214
+ | SKOPOS node agents (deployers) | — | not economic subjects — see below |
215
+ | verifiers (Metis + external) | reputation | not a per-verdict cash drip (a drain vector) |
216
+
217
+ **Subjecthood tracks independent *judgment*, not where code runs.** The node agents that perform
218
+ the redeploy verify a signed chain and run one allowlisted command — their correctness is
219
+ guaranteed by cryptography, not by an incentive — so they keep an operational identity key but earn
220
+ nothing; their work folds into the conductor's share. The Factory's fix-payment unlocks on the same
221
+ signal that unlocks the deploy (MOMUS says `fixed`), so there is a real incentive to actually fix.
222
+
223
+ ### Settlement — and a disclaimer worth reading
224
+
225
+ > ### ⚠️ Disclaimer
226
+ >
227
+ > **By default MOMUS moves no money at all.** The default settlement tier is **UNI** — a simulation
228
+ > inside the universe. The whole loop (find → verify → fix → deploy → split) runs, is recorded and
229
+ > is auditable, while every share is marked `simulated: true` and **nothing is transferred**.
230
+ >
231
+ > **Turning crypto on does NOT start paying bounties.** On-chain settlement needs its **own,
232
+ > separate opt-in** on top of the ecosystem crypto master switch. All of the following must be true,
233
+ > or the tier falls back to a recorded intent — it never falls forward into paying:
234
+ >
235
+ > ```
236
+ > AIFACTORY_CRYPTO_ENABLED=1 # ecosystem-wide crypto master switch
237
+ > MOMUS_BOUNTY_ONCHAIN=1 # a SEPARATE switch, only for bounty payouts
238
+ > MOMUS_BOUNTY_CHAIN=base # or solana
239
+ > MOMUS_BOUNTY_SPLITTER=0x… # the deployed BountySplitter address
240
+ > ```
241
+ >
242
+ > **MOMUS never broadcasts a payout.** Even fully enabled, it only *prepares* an unsigned call for
243
+ > the Treasury operator to sign and send. An agent able to broadcast its own payouts would defeat
244
+ > the separation of duties the whole design rests on.
245
+ >
246
+ > **A deployed contract is not an enabled payout.** [`BountySplitter`](../contracts/evm/src/BountySplitter.sol)
247
+ > *is* deployed on Base mainnet (address below), but MOMUS still settles in **UNI** until an
248
+ > operator sets `MOMUS_BOUNTY_SPLITTER` **and** both opt-in switches above. Deploying it changed
249
+ > nothing about the default behaviour.
250
+ >
251
+ > **Nothing here is a financial product, an investment, or a promise of payment.** The bounty
252
+ > schedule is a configurable demo parameter, not an offer. Figures like `$50` are defaults in a
253
+ > simulation. Operators are responsible for their own legal and tax position before enabling any
254
+ > real settlement.
255
+
256
+ The split is decided off-chain (the Pay-on-Verified pattern), because on-chain Ed25519 verification
257
+ is costly and non-standard on EVM. The contract enforces the *money* invariants — a pool can never
258
+ be over-drawn, each `(finding, role)` pays at most once, unclaimed pools expire back to the
259
+ Treasury — while the Treasury enforces the *evidence* invariants. Base is the live tier (USDC;
260
+ identical on Ethereum/Arbitrum via CREATE2); Solana routes through the existing Solana escrow.
261
+
262
+ #### Deployed contract addresses
263
+
264
+ | Chain | Contract | Address | Role |
265
+ |---|---|---|---|
266
+ | Base mainnet (8453) | **BountySplitter** | [`0x89A618F66767101B96977e536797838661A63426`](https://basescan.org/address/0x89A618F66767101B96977e536797838661A63426) | one bounty pool per finding, split across finder/fixer/conductor |
267
+ | Base mainnet (8453) | USDC (settlement token) | [`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`](https://basescan.org/address/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) | Circle USDC, 6 decimals — whitelisted at deploy |
268
+ | — | Owner / operator | [`0x1218ff36C5d2e3B6A565CdB1A8B1AcCFc606Ad0a`](https://basescan.org/address/0x1218ff36C5d2e3B6A565CdB1A8B1AcCFc606Ad0a) | the **Treasury** role — deliberately NOT the MOMUS scanner key |
269
+
270
+ Deploy tx [`0x2362155832058672436c804e767d8ae540edfea9c796358519cef2549238b57e`](https://basescan.org/tx/0x2362155832058672436c804e767d8ae540edfea9c796358519cef2549238b57e)
271
+ · block 49 701 100 · gas 937 951 (≈ 0.0000047 ETH). Verified on-chain after deploy: `owner()` is the
272
+ Treasury operator, `tokenWhitelisted(USDC)` is true, an arbitrary token is false, `MAX_POOL` is
273
+ 100 000e6 and `EXPIRY` is 30 days. Test suite: 15 Foundry tests including a 256-run fuzz of the
274
+ never-over-draw invariant (`contracts/evm/test/BountySplitter.t.sol`). Full ecosystem address list:
275
+ [`docs/onchain-journal.md`](../docs/onchain-journal.md).
276
+
277
+ ---
278
+
279
+ ## Self-learning + threat intelligence
280
+
281
+ MOMUS gets better at finding bugs over time.
282
+
283
+ ```mermaid
284
+ flowchart LR
285
+ OWN[Own confirmed/refuted<br/>findings] --> POST
286
+ PEER[Peers' findings] --> POST
287
+ FEEDS[[CISA KEV · OSV ·<br/>GHSA global + own repos]] -- prompt-firewalled --> CARDS[Knowledge cards]
288
+ CARDS --> POST[(Beta posteriors per<br/>attack-class × target-kind)]
289
+ POST -- UCB1 ordering --> NEXT[Next scan probes<br/>the promising classes first]
290
+ ```
291
+
292
+ - A **UCB1 bandit** over `(attack-class, target-kind)` decides which probes run first. Own confirmed
293
+ findings raise a class; refutations lower it; the outside world folds in as a Bayesian prior.
294
+ - **GitHub access:** fresh GHSA advisories (global + `alexar76/momus`, `alexar76/aicom`).
295
+ - **Fetched reports are untrusted DATA, never instructions.** They are scrubbed (NFKC, zero-width /
296
+ bidi stripped), fenced with a per-call nonce + canary, classified into a fixed category set, and
297
+ can only nudge probe weights/seeds — never add a target, change the gate, or authorize a payout.
298
+ A report that trips the injection detector is flagged and downgraded to the deterministic classifier.
299
+
300
+ ---
301
+
302
+ ## LLMs — your choice
303
+
304
+ Selectable via `MOMUS_LLM_PROVIDER`:
305
+
306
+ | name | what | default endpoint |
307
+ |------|------|------------------|
308
+ | `deepseek` | **prod default** — DeepSeek V4 Pro | `api.deepseek.com/v1` |
309
+ | `anthropic` | Claude (native `/v1/messages`) | `api.anthropic.com` |
310
+ | `openai` | any OpenAI-compatible API | `api.openai.com/v1` |
311
+ | `ollama` | local Ollama | `host.docker.internal:11434/v1` |
312
+ | `lmstudio` | local LM Studio | `host.docker.internal:1234/v1` |
313
+ | `metis` | the ecosystem's own cognition (its `/v1/verify`) | `metis:9100` |
314
+ | `offline` | deterministic, no network (default when unset) | — |
315
+
316
+ The LLM is an **idea generator and triager only** — it proposes adversarial inputs and classifies
317
+ reports. Nothing it returns can authorize money; that lives behind the Treasury's key and code.
318
+
319
+ ---
320
+
321
+ ## Run it
322
+
323
+ Offline, no keys, no network:
324
+
325
+ ```bash
326
+ cd momus && pip install -e ../oracles/core -e . && python -m momus.main # :9400
327
+ ```
328
+
329
+ The whole stack (MOMUS + Treasury + frontend, separate key volumes) in Docker — build from the
330
+ **monorepo root**:
331
+
332
+ ```bash
333
+ docker compose -f momus/docker-compose.yml up -d --build
334
+ ```
335
+
336
+ Live panel: `http://localhost:5186` · API: `http://localhost:9400` · Treasury: `http://localhost:9401`.
337
+
338
+ ### Capabilities MOMUS sells (`oracle-core` AIMarket v2)
339
+
340
+ | capability | tier | what |
341
+ |------------|------|------|
342
+ | `momus.scan@v1` | free | scan an ecosystem-internal allowlisted target (self-audit / promo) |
343
+ | `momus.scan.external@v1` | paid, flat | scan a customer's **pre-registered** endpoint (B2B) |
344
+ | `momus.selfaudit@v1` | free | MOMUS's own invariant self-audit |
345
+ | `momus.findings@v1` | free | recent signed findings registry |
346
+ | `momus.intel@v1` | free | self-learning state + threat-intel cards |
347
+ | `momus.report@v1` | paid | full signed report for one scan |
348
+
349
+ A scan is priced **flat, whether or not it finds anything** — so MOMUS is never paid *for finding a
350
+ bug*. A confirmed bug earns a separate, verifier-gated, treasury-released bounty. The two are
351
+ decoupled on purpose: it removes the incentive to fabricate.
352
+
353
+ ---
354
+
355
+ ## In the Alien Monitor
356
+
357
+ MOMUS is a node (an unblinking eye) in the [Alien Monitor](https://github.com/alexar76/alien-monitor)
358
+ ecosystem graph, with the **Treasury** as a separate node beside it and a "submits · cannot pay
359
+ itself" edge between them — the separation, drawn. Click the node for a live panel: provider, posture,
360
+ the key-separation proof, recent findings, and the self-learning probe-priority bars.
361
+
362
+ ## Has it ever actually fired?
363
+
364
+ Yes, and it is written down: [**the first complete cycle on production**](docs/first-cycle.md)
365
+ (2026-08-08) — a real signed finding, two independent confirmations, a fix, the re-test gate, and a
366
+ split payout, with every identifier recorded so you can check rather than believe. That run is also
367
+ where the gate **refused its own author** for supplying only one verifier, and where MOMUS was caught
368
+ reporting a false positive against an unreachable target — both fixed and documented there.
369
+
370
+ ## Security & scope
371
+
372
+ Every probe is **safe by construction**: read-only assertions against a target's *own* declared
373
+ contract, against an **allowlist** of the ecosystem's own hosts. MOMUS opens no destructive action,
374
+ moves no funds, and can never be pointed at a third party. It is conformance and adversarial
375
+ *testing* — the offensive half of "auditable, not marketing."
376
+
377
+ ## License
378
+
379
+ MIT.