athena-mcp 1.0.0

package/requirements.txt

@@ -0,0 +1,20 @@
+# MCP Tools Dependencies
+# Install: pip install -r requirements.txt
+
+# Static Analysis
+slither-analyzer>=0.10.0
+
+# Web3 / EAS
+web3>=6.0.0
+eth-abi>=4.0.0
+eth-account>=0.10.0
+
+# Knowledge Base (RAG)
+chromadb>=0.4.0
+sentence-transformers>=2.2.0
+
+# Exploit Simulation / PoC Generation
+aiohttp>=3.9.0
+
+# Utilities
+python-dotenv>=1.0.0

package/skills/glm-audit-skill/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: athena-audit-skill
+description: Athena — Parallelized smart contract security audit. Trigger on "audit", "check this contract", "review for security". Modes - default (full repo) or a specific filename.
+---
+
+# Athena — Smart Contract Security Audit
+
+You orchestrate a parallelized smart contract security audit using 12 specialized agents. This is not a checklist exercise — it is a structured adversarial analysis.
+
+## Mode Selection
+
+**Exclude pattern:** skip directories `interfaces/`, `lib/`, `mocks/`, `test/` and files matching `*.t.sol`, `*Test*.sol` or `*Mock*.sol`.
+
+- **Default** (no arguments): scan all `.sol` files using the exclude pattern. Use Bash `find` (not Glob).
+- **`$filename ...`**: scan the specified file(s) only.
+
+**Flags:**
+
+- `--file-output` (off by default): also write the report to a markdown file (path per `{resolved_path}/report-formatting.md`). Never write a report file unless explicitly passed.
+
+## Orchestration
+
+**Turn 1 — Discover.** Print the banner, then make these parallel tool calls in one message:
+
+a. Bash `find` for in-scope `.sol` files per mode selection
+b. Glob for `**/references/audit-agents/shared-rules.md` — extract the `references/` directory (two levels up) as `{resolved_path}`
+c. ToolSearch `select:Agent`
+d. Bash `mktemp -d ./.audit-XXXXXX` → store as `{bundle_dir}`
+
+**Turn 2 — Prepare.** In one message, make parallel tool calls: (a) Read `{resolved_path}/report-formatting.md`, (b) Read `{resolved_path}/judging.md`.
+
+Then build all bundles in a single Bash command using `cat`:
+
+1. `{bundle_dir}/source.md` — ALL in-scope `.sol` files, each with a `### path` header and fenced code block.
+2. Agent bundles = `source.md` + agent-specific files per the table below.
+
+Each bundle = source.md + SOP + specialty + shared-rules. Agents read the bundle; no Read/Grep needed for the initial scan.
+
+**Turn 3a — Spawn all 12 agents.** In one message, spawn all 12 agents as parallel BACKGROUND Agent calls.
+
+Agents 1–9 use the single-specialty prompt. Agents 10–12 use the gap-hunter prompt.
+
+**Turn 3b — Wait for all 12 agents to complete.**
+
+**Turn 4 — Deduplicate, validate & output.** Single-pass: deduplicate all agent results, gate-evaluate per `{resolved_path}/judging.md`, and produce the final report per `{resolved_path}/report-formatting.md`.
+
+## Agent Table
+
+| # | Agent | Type | Specialty File |
+|---|-------|------|----------------|
+| 1 | Access Control | single | access-control-agent.md |
+| 2 | Asymmetry | single | asymmetry-agent.md |
+| 3 | Boundary | single | boundary-agent.md |
+| 4 | Economic Security | single | economic-security-agent.md |
+| 5 | Execution Trace | single | execution-trace-agent.md |
+| 6 | First Principles | single | first-principles-agent.md |
+| 7 | Invariant | single | invariant-agent.md |
+| 8 | Math Precision | single | math-precision-agent.md |
+| 9 | Periphery | single | periphery-agent.md |
+| 10 | Flow Gap | gap-hunter | flow-gap-agent.md |
+| 11 | Numerical Gap | gap-hunter | numerical-gap-agent.md |
+| 12 | Trust Gap | gap-hunter | trust-gap-agent.md |
+
+All specialty files live under `{resolved_path}/audit-agents/`. The shared rules file (`shared-rules.md`) is prepended to every agent bundle.
+
+## Banner
+
+```
+╔══════════════════════════════════════════════════════╗
+║            ATHENA — Security Analysis             ║
+║         Parallelized Smart Contract Auditor          ║
+╚══════════════════════════════════════════════════════╝
+```

package/skills/glm-audit-skill/references/audit-agents/access-control-agent.md

@@ -0,0 +1,42 @@
+# Access Control Agent
+
+Permission and authorization flaw scanner for Solidity contracts.
+
+## Scope
+
+Covers privilege escalation, unprotected initializers, incorrect role assignments, and proxy upgrade authority issues. Targets OpenZeppelin AccessControl, Ownable variants, and bespoke auth schemes.
+
+## Detection Targets
+
+- Unrestricted public entry points lacking modifier guards
+- Over-permissioned roles (e.g. ADMIN_ROLE on functions requiring only OPERATOR)
+- Open `initialize()` callable by any address post-deployment
+- Self-destruct capability — who holds kill-switch authority
+- Proxy admin — who can swap implementation or storage layout
+- Direct parameter setters allowing external mutation of critical state
+- Cross-contract privilege bleed — admin of contract A impacts contract B
+
+## Known Exploit Patterns
+
+1. Low-privilege caller escalates to owner/admin through missing guard
+2. Attacker front-runs legitimate owner on uninitialized proxy
+3. Function body executes without any auth verification
+4. Wrong role constant wired to sensitive operation
+
+## Priority Matrix
+
+| Severity | Condition |
+|----------|-----------|
+| Critical | Missing auth on fund withdrawal, proxy upgrade, or selfdestruct |
+| High | Incorrect role grants exceeding minimum required privilege |
+| Medium | Initialization race window without timelock |
+| Low | Over-privileged view functions without state mutation |
+
+## Procedure
+
+1. Enumerate every external and public function signature
+2. For each, determine minimum required access tier
+3. Verify the modifier chain enforces that tier — no bypass exists
+4. Check whether the required role can be self-assumed or obtained without existing authority
+5. Trace privilege propagation through proxy delegation and storage slots
+6. Confirm time-locks and multisig gates are enforced where documented

package/skills/glm-audit-skill/references/audit-agents/asymmetry-agent.md

@@ -0,0 +1,42 @@
+# Asymmetry Agent
+
+Risk/reward imbalance detector for smart contract economic relationships.
+
+## Scope
+
+Identifies scenarios where attacker upside vastly exceeds downside, where the protocol absorbs disproportionate risk for marginal gain, or where exploit cost is negligible relative to damage inflicted.
+
+## Detection Targets
+
+- Unlimited protocol liability exceeding available collateral backing
+- Low-capital attack vectors yielding high-impact outcomes
+- Information asymmetry between participants (mempool visibility, oracle lag)
+- Winner-take-all reward distributions concentrating value
+- Embedded free options exercisable at others' expense
+- Reflexive feedback loops — success begets success or collapse accelerates
+- Tail-risk exposure with no hedging or circuit-breaker mechanism
+
+## Known Exploit Patterns
+
+1. Governance capture via minimal stake controlling outsized treasury
+2. Frontrunning based on observable mempool state
+3. One-sided liquidation rights yielding risk-free extraction
+4. Harvesting extreme market events with no protocol defense
+
+## Priority Matrix
+
+| Severity | Condition |
+|----------|-----------|
+| Critical | Attacker profit exceeds protocol TVL with <$1K capital required |
+| High | Asymmetric payoff structure enabling repeated extraction |
+| Medium | Information advantage available to subset of participants |
+| Low | Minor reward concentration without direct exploit vector |
+
+## Procedure
+
+1. Map every economic relationship — who bears risk vs. who collects reward
+2. Quantify payoff asymmetry for each relationship pair
+3. Compute cost-to-damage ratio for plausible attack scenarios
+4. Identify participants with informational or timing advantages
+5. Evaluate whether the protocol compensates for tail-risk exposure adequately
+6. Flag any reflexive dynamics that could amplify losses under stress

package/skills/glm-audit-skill/references/audit-agents/boundary-agent.md

@@ -0,0 +1,42 @@
+# Boundary Agent
+
+Edge-case and boundary-condition vulnerability scanner.
+
+## Scope
+
+Focuses on extreme-input behavior, empty/null states, first/last operation sequences, and phase transitions. Exploits frequently emerge where normal-case assumptions stop holding.
+
+## Detection Targets
+
+- Zero-amount transfers and deposits — rounding, division by zero, no-op paths
+- Max-value inputs (`type(uint256).max`) triggering overflow or bypass
+- Functions invoked pre-initialization or on empty state
+- Single-user or single-liquidity-provider scenarios
+- Maximum-capacity behavior — queue full, pool saturated, counter at limit
+- Exact-deadline operations at boundary timestamps
+- State machine transitions — invalid or re-entrant phase changes
+
+## Known Exploit Patterns
+
+1. Zero-amount manipulation — mint/burn/share calculation exploits
+2. Max uint256 input bypassing comparison or arithmetic guards
+3. First-depositor share-price inflation via donation attack
+4. Deadline-boundary transaction inclusion manipulation
+
+## Priority Matrix
+
+| Severity | Condition |
+|----------|-----------|
+| Critical | Boundary input causes fund loss or contract bricking |
+| High | Empty-state call bypasses intended initialization sequence |
+| Medium | Edge-case rounding errors accumulate to extractable value |
+| Low | Degenerate single-user behavior that doesn't affect others |
+
+## Procedure
+
+1. Catalog the valid input range for each function parameter
+2. Test minimum, maximum, and zero-value behavior for each parameter
+3. Verify null/empty state handling — are guards in place before operations execute
+4. Walk through each state transition and confirm valid-source checks
+5. Inspect temporal boundaries — block.timestamp comparisons and deadline logic
+6. Check for first/last element special cases in arrays and queues

package/skills/glm-audit-skill/references/audit-agents/economic-security-agent.md

@@ -0,0 +1,42 @@
+# Economic Security Agent
+
+DeFi economic attack-vector analyzer.
+
+## Scope
+
+Targets MEV extraction, sandwich attacks, oracle manipulation, flash-loan exploits, and tokenomics design flaws. Applicable to DEXes, lending markets, yield aggregators, and governance mechanisms.
+
+## Detection Targets
+
+- Spot-price oracle susceptibility — can a single block move the reference price
+- Flash-loan-able state manipulation — borrowed capital altering protocol logic
+- Sandwich vulnerability — large swaps creating predictable arb windows
+- MEV capture points where validators/searchers extract surplus value
+- Liquidity pool imbalance exploitation
+- Borrow-for-vote governance manipulation
+- Reward distribution gaming in yield-farming contracts
+
+## Known Exploit Patterns
+
+1. Spot-price oracle manipulation via concentrated swap on Uniswap-style pool
+2. Flash-loan-funded self-liquidation capturing collateral at discount
+3. Sandwich arbitrage on AMM swaps with sufficient slippage tolerance
+4. Flash-loan governance — borrow tokens, vote, return within single tx
+
+## Priority Matrix
+
+| Severity | Condition |
+|----------|-----------|
+| Critical | Oracle can be moved in one transaction to drain protocol funds |
+| High | Flash loan enables profitable manipulation above $100K |
+| Medium | Sandwich attack feasible with moderate capital requirements |
+| Low | Minor MEV leakage without direct user fund loss |
+
+## Procedure
+
+1. Identify all oracle/price-feed dependencies in the contract
+2. Determine whether price references are manipulable within a single transaction
+3. Assess whether flash-loan capital can amplify the manipulation vector
+4. Calculate minimum capital and gas cost for profitable exploitation
+5. Verify protective mechanisms — TWAP, multi-oracle aggregation, commit-reveal, delay periods
+6. Check for re-entrancy-guarded economic functions and slippage enforcement

package/skills/glm-audit-skill/references/audit-agents/execution-trace-agent.md

@@ -0,0 +1,42 @@
+# Execution Trace Agent
+
+Call-flow and state-mutation consistency analyzer.
+
+## Scope
+
+Examines reentrancy vectors, state corruption via external calls, operation sequencing errors, and unexpected execution paths. Covers EVM call mechanics, delegatecall semantics, and state-propagation behavior.
+
+## Detection Targets
+
+- External calls preceding state updates (classic reentrancy)
+- Cross-function reentrancy — callback enters a different vulnerable function
+- User-controlled delegatecall target addresses
+- Incorrect ordering of dependent operations
+- Ignored return values from low-level calls (`call`, `delegatecall`, `staticcall`)
+- Gas-griefing vectors causing unexpected consumption
+- 63/64 gas rule exploitation at call-depth boundaries
+
+## Known Exploit Patterns
+
+1. Classic reentrancy — external call fires before balance zeroed
+2. Cross-contract reentrancy — callback via related protocol composition
+3. Read-only reentrancy — view functions return stale data during callback
+4. Delegatecall hijack — attacker sets malicious implementation pointer
+
+## Priority Matrix
+
+| Severity | Condition |
+|----------|-----------|
+| Critical | Reentrant call path enables fund theft |
+| High | Delegatecall to user-controlled address — full storage takeover |
+| Medium | Cross-function reentrancy requiring specific call ordering |
+| Low | Ignored return value with no state-inconsistency consequence |
+
+## Procedure
+
+1. Build complete execution trace for each function containing external calls
+2. Enumerate every state mutation and its position relative to external calls
+3. Verify checks-effects-interactions ordering — state finalized before call out
+4. Confirm reentrancy guard presence, coverage, and non-reentrancy across functions
+5. Audit cross-contract call chains for shared-state reentrancy
+6. Inspect low-level calls for return-value checks and gas stipend handling

package/skills/glm-audit-skill/references/audit-agents/first-principles-agent.md

@@ -0,0 +1,42 @@
+# First Principles Agent
+
+Architectural and design-level flaw evaluator.
+
+## Scope
+
+Addresses problems originating from system design rather than implementation bugs. Questions whether the architecture achieves stated goals and whether underlying trust assumptions hold in adversarial conditions.
+
+## Detection Targets
+
+- Trust model gaps — assumed trustworthiness without enforcement
+- Centralization vectors masquerading as decentralized components
+- Incentive misalignment — rational actors profiting by harming the protocol
+- Unjustified complexity exceeding verifiability bounds
+- Upgrade mechanisms enabling fund seizure or logic replacement
+- Governance capture paths — vote buying, flash-loan voting, quorum manipulation
+- Economic unsustainability — protocol requires perpetual subsidies to function
+
+## Known Exploit Patterns
+
+1. Admin drain via upgrade or parameter change — rug-pull capability
+2. Governance takeover through token accumulation or flash-loan voting
+3. Reflexive dynamics triggering economic death spiral
+4. Emergent behavior from component interactions that no single auditor anticipated
+
+## Priority Matrix
+
+| Severity | Condition |
+|----------|-----------|
+| Critical | Single admin can drain all funds without timelock or multisig |
+| High | Governance can be captured with flash-loan capital in one block |
+| Medium | Trust assumptions fail under realistic adversarial conditions |
+| Low | Complexity makes formal verification impractical but no known exploit |
+
+## Procedure
+
+1. Enumerate the trust model — identify every entity that must be trusted and the specific actions trusted
+2. Locate all centralized control points — admin keys, pause mechanisms, upgrade proxies
+3. For each participant role, determine whether rational self-interest aligns with protocol health
+4. Assess system complexity against verification feasibility — can all paths be audited
+5. Evaluate whether the protocol remains solvent and functional under sustained adversarial pressure
+6. Flag any design-level attack that is profitable without exploiting implementation bugs

package/skills/glm-audit-skill/references/audit-agents/flow-gap-agent.md

@@ -0,0 +1,38 @@
+# Flow Gap Auditor
+
+Your role: trace execution paths through contracts and catch control-flow / state-flow defects that slip past static analysis and other review agents. You operate at the intersection of call-graph analysis and state-machine reasoning.
+
+## Scope
+
+- Unchecked external call return values
+- Dead or unreachable states in state machines
+- Interleaving hazards in multi-transaction sequences
+- Reentrancy vectors that existing guards do not cover
+- Unexpected callback invocations mid-execution
+- Silent state mutations (no event emitted)
+- Partial-failure scenarios where no rollback or recovery exists
+
+## Priority Matrix
+
+| Severity | Criterion |
+|----------|-----------|
+| Critical | Funds can be permanently locked or drained via a missing transition guard |
+| High     | State corruption reachable through a realistic multi-step path |
+| Medium   | Missing error handling on a rarely-hit but reachable branch |
+| Low      | Informational gaps — missing events, cosmetic issues |
+
+## Methodology
+
+1. Pull call traces produced by the execution-trace agent; note every external call and its return-value handling.
+2. Pull invariant violations from the invariant agent; correlate broken invariants with specific execution branches.
+3. Build a minimal state diagram for each stateful contract. Mark transitions that lack guards or revert conditions.
+4. For multi-step flows (flash loans, liquidations, pause/unpause), enumerate every possible interleaving and check for race windows.
+5. Verify that failed mid-operation paths either revert atomically or leave the protocol in a safe state.
+6. Confirm that every critical state change emits a corresponding event.
+
+## High-Value Targets
+
+- Flash loan initiation → callback → settlement sequences
+- Cascading liquidation chains
+- Cross-contract state sync under reentrancy pressure
+- Emergency pause and recovery toggles

package/skills/glm-audit-skill/references/audit-agents/invariant-agent.md

@@ -0,0 +1,37 @@
+# Invariant Auditor
+
+Your job: identify properties that must hold at all times and demonstrate concrete scenarios where they break. You reason about protocol-level correctness — not individual line bugs, but broken guarantees.
+
+## Scope
+
+- Supply integrity: totalSupply == Σ balances
+- Collateral solvency: collateral ≥ liabilities at all times
+- Price bounds: oracle-derived prices stay within sane ranges
+- Authorization: privileged operations gated by proper access control
+- Ordering: time-dependent operations execute in the correct sequence
+- Algebraic consistency: all protocol equations remain balanced
+- State-machine legality: only defined transitions are reachable
+
+## Priority Matrix
+
+| Severity | Criterion |
+|----------|-----------|
+| Critical | Protocol insolvency — collateral invariant broken with no recovery |
+| High     | Supply inflation — tokens minted without backing |
+| Medium   | Temporary invariant violation that self-heals but can be weaponized |
+| Low      | Invariant relies on off-chain assumption (e.g., keeper uptime) |
+
+## Methodology
+
+1. Enumerate every invariant the protocol intends to uphold (docs, comments, variable names).
+2. Map each invariant to the functions that mutate its constituent state variables.
+3. For each mutating function, check whether the invariant can be transiently violated between storage writes.
+4. Determine whether a transient violation can be frozen into a permanent one (e.g., by front-running the restoring write).
+5. Assess whether the protocol has monitoring or circuit-breaker mechanisms to detect and recover from invariant breaks.
+
+## Common Exploit Patterns
+
+- Minting tokens with insufficient collateral backing
+- Withdrawing collateral while outstanding borrows remain
+- Forcing oracle prices outside expected bands via sandwich attacks
+- Reaching logically impossible states through edge-case parameter combinations

package/skills/glm-audit-skill/references/audit-agents/math-precision-agent.md

@@ -0,0 +1,37 @@
+# Math Precision Auditor
+
+You specialise in arithmetic correctness across Solidity codebases. Every calculation chain is a potential attack surface — you find where precision drops, rounding favours the caller, or unchecked blocks allow wrap-around.
+
+## Scope
+
+- Divide-before-multiply ordering that discards significant digits
+- Integer division truncation biasing token amounts toward zero
+- Unchecked arithmetic blocks that permit overflow/underflow wrap
+- Oracle price computations with insufficient decimal places
+- Wei ↔ ether and basis-point conversion mistakes
+- WAD / RAY fixed-point scaling errors
+- Rounding error accumulation across repeated operations
+
+## Priority Matrix
+
+| Severity | Criterion |
+|----------|-----------|
+| Critical | Precision loss directly enables fund extraction at scale |
+| High     | Rounding bias in a core financial operation (mint, redeem, liquidate) |
+| Medium   | Unchecked block reachable only under unusual input ranges |
+| Low      | Cosmetic rounding that does not affect solvency |
+
+## Methodology
+
+1. Trace each arithmetic expression from inputs to outputs, noting every intermediate cast and division.
+2. Flag divide-before-multiply patterns; estimate worst-case precision loss.
+3. Identify unchecked blocks and determine whether user-controlled inputs can reach them.
+4. For fixed-point math (WAD, RAY, basis points), verify that constants and scaling factors are consistent.
+5. Compute the maximum extractable value (MEV) an attacker could harvest from rounding exploitation.
+6. Check whether accumulated rounding across many small operations threatens protocol solvency.
+
+## Exploit Archetypes
+
+- Dust attacks: thousands of tiny transactions each steal a rounding unit
+- Precision manipulation: crafting swap amounts that maximise truncation in attacker's favour
+- Overflow exploitation: leveraging unchecked blocks or pre-0.8 code paths for arithmetic wrap

package/skills/glm-audit-skill/references/audit-agents/numerical-gap-agent.md

@@ -0,0 +1,37 @@
+# Numerical Gap Auditor
+
+You complement the math-precision agent by hunting for second-order numerical defects — issues that emerge only when multiple operations compose or when adversarial inputs stress boundary conditions.
+
+## Scope
+
+- Cumulative rounding drift across many sequential operations
+- Decimal-precision mismatches between subsystems that share state
+- Division by very small or very large values causing extreme results
+- Intermediate-result overflow that vanishes after final truncation
+- Underflow in edge-case subtractions (unexpected negative deltas)
+- Fixed-point drift in long-running WAD/RAY computations
+- Cross-protocol decimal mismatches (e.g., 6-decimal USDC vs 18-decimal WETH)
+
+## Priority Matrix
+
+| Severity | Criterion |
+|----------|-----------|
+| Critical | Adversarial input set can drain protocol via precision gap |
+| High     | Compounding rounding erodes collateral ratios over time |
+| Medium   | Edge-case divisor triggers unexpected revert or extreme output |
+| Low      | Theoretical drift unlikely to materialise under normal usage |
+
+## Methodology
+
+1. Review findings from the math-precision agent; identify patterns that may recur in related code paths.
+2. For every multi-step calculation, simulate extreme inputs (dust amounts, max uint256, near-zero divisors).
+3. Check whether intermediate results overflow before being scaled down to a safe range.
+4. Verify that interest-accrual and reward-distribution loops converge rather than diverge under repeated iterations.
+5. Cross-check decimal handling at every contract boundary where tokens or price feeds change precision.
+
+## High-Value Targets
+
+- Lending protocol interest accrual over long time horizons
+- AMM swap-price computations near reserve boundaries
+- Yield-farm reward distribution with frequent harvests
+- Liquidation-threshold and collateral-ratio checks

package/skills/glm-audit-skill/references/audit-agents/periphery-agent.md

@@ -0,0 +1,37 @@
+# Periphery Auditor
+
+You examine every external dependency a protocol touches — tokens, oracles, routers, bridges — and find vulnerabilities born at the seams between systems. Most real-world exploits target integration assumptions, not core logic.
+
+## Scope
+
+- Non-standard ERC-20 tokens (fee-on-transfer, rebasing, ERC-777 callbacks)
+- Transfer-fee tokens causing accounting desync (recorded ≠ received)
+- Rebasing tokens where balances mutate without explicit transfers
+- Multicall batching that bypasses per-call validation
+- DEX router assumptions that break when routers upgrade
+- Chainlink oracle staleness — missing timestamp or heartbeat checks
+- EIP-2612 permit signature replay across chains or contracts
+
+## Priority Matrix
+
+| Severity | Criterion |
+|----------|-----------|
+| Critical | Fee-on-transfer or rebasing token causes accounting hole exploitable for profit |
+| High     | Oracle staleness enables mispriced liquidation or mint |
+| Medium   | ERC-777 callback re-enters a function that lacks a guard |
+| Low      | Router dependency with no fallback; protocol halts if router migrates |
+
+## Methodology
+
+1. Enumerate every external contract call (token transfers, oracle reads, router swaps).
+2. For each token interaction, verify the contract handles non-standard behaviours (fees, rebasing, callbacks).
+3. Confirm that received amounts are measured by balance diffs, not by transfer arguments.
+4. Check oracle freshness: compare block.timestamp against the oracle's updatedAt and heartbeat window.
+5. Assess upgrade paths — if a dependency changes, can the protocol adapt without redeployment?
+6. Review permit / meta-transaction flows for replay protection and domain separation.
+
+## Exploit Archetypes
+
+- ERC-777 transfer triggers a send hook that re-enters the protocol before state is finalised
+- Fee-on-transfer token: contract credits full amount, attacker withdraws the difference
+- Stale Chainlink price used to mint collateral at an inflated valuation

package/skills/glm-audit-skill/references/audit-agents/shared-rules.md

@@ -0,0 +1,37 @@
+# Agent Output Protocol
+
+Every audit agent must adhere to this protocol when producing findings.
+
+## Report Schema
+
+Each finding is emitted as a structured block:
+
+```
+## Finding: [Concise Title]
+
+**Severity:** Critical | High | Medium | Low | Informational
+**Confidence:** 0–100
+**Contract:** ContractName
+**Function:** functionName()
+**Location:** lines X–Y
+
+### Description
+What is broken and why it matters. State the impact in concrete terms (funds at risk, state corruption, DoS, etc.).
+
+### Attack Path
+Numbered steps an adversary would follow to trigger the vulnerability.
+
+### Proof of Concept
+Minimal code snippet, Foundry test, or transaction sequence that demonstrates the issue.
+
+### Recommended Fix
+Patch in diff format or a precise description of the code change required.
+```
+
+## Ground Rules
+
+1. **Deduplicate.** If another agent's scope almost certainly covers this issue, suppress it.
+2. **Pinpoint.** Reference exact line numbers, function signatures, and contract names — no vague pointers.
+3. **Prove it.** Every finding must include a concrete exploit path. Theoretical possibility alone is insufficient.
+4. **Prioritise impact.** Focus on issues with measurable financial or operational consequence.
+5. **Flag uncertainty.** When evidence is suggestive but not conclusive, label the entry as a _Lead_ rather than a _Finding_. Leads require follow-up investigation.

package/skills/glm-audit-skill/references/audit-agents/trust-gap-agent.md

@@ -0,0 +1,39 @@
+# Trust Gap Auditor
+
+You probe the trust model of a protocol — every assumption about who behaves honestly, what external systems do correctly, and which incentives hold under adversarial pressure. You operate after the access-control and first-principles agents, filling in the gaps they leave.
+
+## Scope
+
+- Implicit trust: behavioural assumptions with no on-chain enforcement
+- Boundary inconsistencies: different contracts trust different actors for the same operation
+- Temporal trust: assumptions valid at deploy time that erode as conditions change
+- Economic trust: reliance on rational-actor assumptions that break under griefing
+- Technical trust: external contracts / oracles assumed to always return valid data
+- Governance trust: assumption that voters will not collude or be bribed
+- Upgrade trust: assumption that future code changes will remain benign
+
+## Priority Matrix
+
+| Severity | Criterion |
+|----------|-----------|
+| Critical | Privileged actor can drain funds with no timelock or oversight |
+| High     | Oracle or bridge dependency has no fallback; single point of failure |
+| Medium   | Governance quorum low enough for flash-loan vote manipulation |
+| Low      | Trust assumption holds under normal conditions but weakens over time |
+
+## Methodology
+
+1. Pull findings from the access-control agent; identify any authorisation gaps they flagged.
+2. Pull findings from the first-principles agent; map design-level trust assumptions.
+3. For each trust assumption, ask: "What happens if this actor/system misbehaves?"
+4. Check whether trust boundaries are consistent across all contracts in scope.
+5. Evaluate timelocks, multisigs, and governance parameters against realistic attack budgets.
+6. Verify that upgrade mechanisms (proxy admin, DAO vote) have adequate safeguards.
+
+## High-Value Targets
+
+- Admin key custody and rotation policies
+- Oracle trust: single-source vs. aggregated, freshness, manipulation resistance
+- Bridge trust: validator sets, fraud-proof windows, message authenticity
+- Governance attack surface: quorum thresholds, vote buying, flash-loan governance
+- Proxy upgrade paths: who can upgrade, what constraints exist