From 1e4eef1060188b1c7384c94e0ec59a0f631571ac Mon Sep 17 00:00:00 2001 From: AdriaCarrera Date: Wed, 29 Apr 2026 09:49:26 +0200 Subject: [PATCH] feat: define security audit scope, threat model, and audit automation skills --- .claude/security/SECURITY_SCOPE.md | 251 +++++++++++++++++++++++++ .claude/security/THREAT_MODEL.md | 200 ++++++++++++++++++++ .claude/skills/security-audit/SKILL.md | 23 +++ .claude/skills/security-issue/SKILL.md | 69 +++++++ CLAUDE.md | 53 ++++++ 5 files changed, 596 insertions(+) create mode 100644 .claude/security/SECURITY_SCOPE.md create mode 100644 .claude/security/THREAT_MODEL.md create mode 100644 .claude/skills/security-audit/SKILL.md create mode 100644 .claude/skills/security-issue/SKILL.md create mode 100644 CLAUDE.md diff --git a/.claude/security/SECURITY_SCOPE.md b/.claude/security/SECURITY_SCOPE.md new file mode 100644 index 0000000..075ffd8 --- /dev/null +++ b/.claude/security/SECURITY_SCOPE.md @@ -0,0 +1,251 @@ +# Security Audit Scope + +This document defines the scope and priorities for AI-assisted security audits of the XRPL EVM Sidechain node (`exrpd`). + +## Project Context + +This is a **Cosmos SDK-based blockchain node** that runs an EVM-compatible sidechain for the XRP Ledger. It uses Proof-of-Authority (POA) consensus with authority-gated validator management. The node handles real financial assets (`axrp`/`xrp`) and executes smart contracts via the EVM. + +**Security criticality: HIGH** — vulnerabilities can lead to loss of funds, chain halts, or consensus failures. + +## In-Scope Components + +### Critical + +| Component | Path | Why | +|---|---|---| +| Ante handlers | `app/ante/` | Transaction validation gate — bypasses here affect all txs | +| POA module | `x/poa/` | Authority checks for validator management | +| App wiring | `app/app.go` | Module registration, keeper initialization, upgrade handlers | +| Upgrade handlers | `app/upgrades/` | State migrations run during chain upgrades — bugs here can corrupt state, brick the chain, or open exploit windows post-upgrade | +| CLI entry point | `cmd/exrpd/` | Node configuration, default values, TLS setup | + +### High Priority + +| Component | Path | Why | +|---|---|---| +| Protocol buffers | `proto/` | API surface definition, message validation | +| Type definitions | `types/` | Address prefixes, coin denominations, constants | +| App configuration | `app/config.go` | Chain constants that affect consensus | +| Go module dependencies | `go.mod` | Supply chain risk from third-party modules | +| Encoding config | `app/encoding.go` | Custom signers, legacy type registration, EIP-712 setup — incorrect encoding can cause signature bypass or tx deserialization issues | + +### Infrastructure + +| Component | Path | Why | +|---|---|---| +| CI workflows | `.github/workflows/` | Secret exposure in env/steps, untrusted input in PR triggers, permission scoping | +| Release pipeline | `.goreleaser.yml`, `.github/workflows/goreleaser.yml`, `.github/workflows/release.yml` | Binary integrity — compromised release artifacts affect all node operators | +| Dockerfiles | `Dockerfile`, `tools/cosmovisor/Dockerfile` | Secret leakage (SSH keys in build), unpinned base images, multi-stage hygiene | +| Makefile | `Makefile` | Build flags, CGO settings, embedded variables | +| Branch protection | `.github/workflows/branch.yml`, `.github/workflows/pull-request.yml` | Enforce review requirements, prevent force-push to main | +| CODEOWNERS | `.github/CODEOWNERS` | Ensure security-sensitive paths require appropriate reviewers | + +### Lower Priority + +| Component | Path | Why | +|---|---|---| +| Test utilities | `testutil/` | Only matters if test helpers mask real bugs | +| Integration tests | `tests/` | Verify test coverage gaps | +| Cosmovisor setup | `.github/workflows/cosmovisor.yml`, `tools/cosmovisor/` | Upgrade orchestration — misconfiguration can brick nodes during upgrades | +| Linter/coverage config | `.golangci.yml`, `.testcoverage.yml` | Verify security linters are enabled (e.g., `gosec`) | + +## Out of Scope + +- **Upstream Cosmos SDK** — audited separately by the Cosmos ecosystem. Treat as a dependency: check for known CVEs in `go.mod`, but do not audit internal SDK code. Flag if we override or patch upstream behavior. +- **Upstream CometBFT** — same as above. +- **Upstream `cosmos/evm`** — same as above. Treat as a dependency like Cosmos SDK. Check for version pinning and known vulnerabilities, but do not audit its internals. +- **Smart contracts deployed on the EVM** — application-layer, not node-layer. + +## Trust Boundaries + +These are the points where untrusted input enters the system. Every audit should verify these boundaries are intact. + +``` + +-------------------------+ + External RPCs ------> | gRPC / REST / JSON-RPC | + +------------+------------+ + | + v + +------------+------------+ + | Ante Handlers | <-- Signature, fee, extension validation + +------------+------------+ + | + +-----------------+-----------------+ + | | + v v + +------------+------------+ +------------+------------+ + | Cosmos SDK Modules | | EVM Execution | + | | | | + | auth, bank, staking, | | Smart contract calls | + | gov, authz, slashing, | | via go-ethereum | + | distribution, crisis, | +------------+------------+ + | feegrant, params, | | + | consensus, upgrade | | + +------------+------------+ | + | | + +------- POA (validator mgmt) ------+ + | Authority gate | + | | + v v + +------------+------------+ +------------+------------+ + | State Store (IAVL) | <--- | EVM State (accounts, | + | Consensus-critical | | contracts, storage) | + +-------------------------+ +-------------------------+ + ^ + | + +------------+------------+ + | IBC Middleware | <-- IBC relayer messages + | transfer, ica/host, | + | rate-limiting | + +-------------------------+ +``` + +1. **Network boundary**: gRPC, REST (gRPC-gateway), JSON-RPC endpoints accept external requests. +2. **Transaction validation**: Ante handlers validate signatures, fees, and extension options before execution. +3. **Authority gate**: POA message handlers check `msg.Authority == k.authority` before allowing validator changes. +4. **IBC boundary**: Inter-blockchain messages arrive via IBC with rate limiting (`ibc-apps/modules/rate-limiting`). +5. **EVM boundary**: User-submitted bytecode executes in the EVM sandbox via `go-ethereum`. +6. **Cosmos SDK module boundaries**: The node wires the following upstream SDK modules, each with its own trust assumptions. While their internals are out of scope, the way they are configured, initialized, and composed in `app/app.go` is in scope: + + | Module | Keeper | Security relevance | + |---|---|---| + | `auth` | `AccountKeeper` | Account creation, sequence numbers, signature verification | + | `bank` | `BankKeeper` | Token minting, burning, transfers — blocked addresses list | + | `staking` | `StakingKeeper` | Validator bonding (interacts with POA — verify no bypass) | + | `slashing` | `SlashingKeeper` | Validator penalties — misconfiguration can brick validators | + | `distribution` | `DistrKeeper` | Reward distribution — incorrect wiring can leak or lock funds | + | `gov` | `GovKeeper` | On-chain governance proposals — can trigger arbitrary module changes | + | `crisis` | `CrisisKeeper` | Invariant checking — verify invariants are registered | + | `authz` | `AuthzKeeper` | Grant-based authorization — overly broad grants can escalate privileges | + | `feegrant` | `FeeGrantKeeper` | Fee delegation — potential for fee exhaustion attacks | + | `evidence` | `EvidenceKeeper` | Double-sign evidence handling | + | `upgrade` | `UpgradeKeeper` | Chain upgrade coordination — ties into `app/upgrades/` | + | `params` | `ParamsKeeper` | Legacy parameter changes — verify migration to consensus params | + | `consensus` | `ConsensusParamsKeeper` | Block size, gas limits, validator set changes | + | `transfer` | `TransferKeeper` | IBC token transfers | + | `ica/host` | `ICAHostKeeper` | Interchain accounts — remote chains can execute messages on this chain | + | `rate-limiting` | `RateLimitKeeper` | IBC rate limiting — misconfiguration can allow or block transfers | + +## Audit Focus Areas + +Each audit should spawn a separate agent per focus area below. All areas are reviewed every audit cycle — run them in parallel for efficiency. Each area maps to one or more in-scope components. + +| Area | Components | What to look for | +|---|---|---| +| **POA module** | POA module | Authority check correctness (`msg.Authority == k.authority`), keeper initialization, genesis state validation, alternative code paths to modify the validator set, Bech32 address validation. Cross-module interactions: token minting/burning via BankKeeper (correct module accounts and pool names), staking state mutations (delegation removal, unbonding slashing with correct slash factor, validator token removal, status-based pool routing for Bonded vs Unbonding/Unbonded), staking hooks invocation order (BeforeValidatorModified, BeforeValidatorSlashed), and edge cases around existing delegations/unbondings during add/remove flows | +| **Authorization & access control** | App wiring | Missing permission checks, privilege escalation via `authz`/`gov`, keeper exposure across module boundaries | +| **Transaction validation** | Ante handlers, App wiring | Ante handler routing between EVM/Cosmos, extension option validation, signature bypass, fee circumvention | +| **EVM integration** | Ante handlers, App wiring | EVM tx routing, gas metering between Cosmos and EVM layers, precompile registration | +| **IBC & cross-chain** | App wiring | Rate limiting config, IBC message validation, channel security, ICA host permissions | +| **Upgrade handlers** | Upgrade handlers | State migration correctness, non-determinism, missing or stale upgrade handlers | +| **Configuration & secrets** | CLI entry point, App configuration, Encoding config | Hardcoded secrets, insecure defaults, TLS config, env var handling | +| **Consensus & state machine** | App wiring, POA module, Type definitions | Non-determinism (map iteration, goroutines, `time.Now()`), module account permissions (Minter/Burner scoping), genesis state validation, address prefix correctness | +| **API surface** | Protocol buffers, Ante handlers | Protobuf message validation, unexpected fields, gRPC/REST endpoint exposure, query handler authorization | +| **Dependency audit** | Go module dependencies | Known CVEs, pinned vs floating versions, dependency confusion | +| **Infrastructure & CI** | CI workflows, Release pipeline, Dockerfiles, Makefile, Branch protection, CODEOWNERS | Secret exposure, unpinned base images, build reproducibility, CI permission scoping | +| **Test coverage** | Test utilities, Integration tests, Linter/coverage config, Cosmovisor setup | Test coverage gaps, security linters enabled (e.g., `gosec`), test helpers that mask real bugs | + +### How to run + +Spawn one `security-reviewer` agent per area. Example: + +``` +claude "Read .claude/security/SECURITY_SCOPE.md and .claude/security/THREAT_MODEL.md. Then perform a security audit focused on: [AREA]. Check the components listed in the scope. Report findings to peersyst/security following the reporting workflow below." +``` + +Or run all areas in parallel by spawning multiple agents in a single prompt. + +## Reporting Workflow + +All findings are reported as GitHub Issues in the **private** `peersyst/security` repository. + +### Labels + +Each issue must have labels from these categories: + +| Category | Labels | Purpose | +|---|---|---| +| Repo | `repo:xrplevm/node`, `repo:xrplevm/evm`, etc. | Filter findings by source repo | +| Severity | `critical`, `high`, `medium`, `low`, `info` | Triage priority | +| Status | `pending`, `accepted`, `discarded` | Triage state (closed = done) | + +### Issue format + +``` +Title: [SEVERITY] Short description of the finding + +Body: +## Area + + + +## Finding + + + +## Location + + + +## Impact + + + +## Recommendation + + + +## Evidence + + +``` + +### Creating a finding + +```bash +gh issue create -R peersyst/security \ + --title "[HIGH] Description of finding" \ + --label "repo:xrplevm/node,high,pending" \ + --body "$(cat <<'EOF' +## Area +POA module + +## Finding +... +## Location +... +## Impact +... +## Recommendation +... +## Evidence +... +EOF +)" +``` + +### Lifecycle + +1. **AI creates issue** with `pending` label +2. **Human triages**: changes to `accepted` (valid, needs fix) or `discarded` (with comment explaining why) +3. **Developer fixes**: closes the issue with a reference to the fixing commit/PR +4. **Next audit**: AI queries existing issues before reporting to avoid duplicates: + +```bash +gh issue list -R peersyst/security --label "repo:xrplevm/node" --state all --json number,title,labels,state +``` + +### Deduplication rules + +- **`pending` or `accepted`**: Do not re-raise. The finding is already tracked. +- **`discarded`**: Do not re-raise the same finding. Read the discard reason — only re-raise if circumstances have materially changed. +- **Closed (done)**: Verify the fix is still in place. If the vulnerability has regressed, open a **new** issue referencing the original. + +## Severity Classification + +- **CRITICAL**: Exploitable now, loss of funds or chain halt possible +- **HIGH**: Exploitable with effort, significant impact +- **MEDIUM**: Requires specific conditions, moderate impact +- **LOW**: Minor issue, defense-in-depth concern +- **INFO**: Observation, no direct security impact but worth noting diff --git a/.claude/security/THREAT_MODEL.md b/.claude/security/THREAT_MODEL.md new file mode 100644 index 0000000..1c88037 --- /dev/null +++ b/.claude/security/THREAT_MODEL.md @@ -0,0 +1,200 @@ +# Threat Model + +Threat model for the XRPL EVM Sidechain node. This document identifies assets, adversaries, and attack surfaces to guide security audits. + +## Assets + +| Asset | Description | Impact if compromised | +|---|---|---| +| Validator set | POA-managed list of block producers | Chain halt, censorship, double-spend | +| User funds | `axrp`/`xrp` balances in accounts | Direct financial loss | +| Consensus state | IAVL state tree, block history | Fork, state corruption, rollback | +| Authority key | The address authorized to manage validators | Full control of validator set | +| Node operator keys | Keys used to sign blocks | Impersonation, invalid blocks | +| IBC channels | Cross-chain communication paths | Cross-chain theft, replay attacks | +| EVM state | Smart contract storage and code | Contract manipulation, fund theft | + +## Adversary Profiles + +| Adversary | Capability | Goal | +|---|---|---| +| External attacker | Sends crafted transactions via RPC | Steal funds, halt chain, bypass fees | +| Malicious validator | Controls one validator node | Censor txs, manipulate ordering | +| Supply chain attacker | Compromises a Go module dependency | Backdoor node binary | +| Rogue insider | Has access to authority key or CI | Add malicious validators, push bad builds | +| Cross-chain attacker | Controls an IBC-connected chain | Forge IBC messages, drain bridge | +| ICA controller | Controls an interchain account on a remote chain | Execute arbitrary messages on this chain via ICA host | + +## Attack Surfaces + +### 1. Transaction Processing + +**Entry**: gRPC, REST, JSON-RPC endpoints + +**Threats**: +- Malformed transactions that bypass ante handler validation +- Extension option confusion (EVM tx routed as Cosmos tx or vice versa) +- Fee bypass or gas manipulation +- Signature validation flaws + +**Key files**: `app/ante/ante.go` + +**What to check**: +- All transaction types are routed to the correct handler chain +- Unknown extension options are rejected (verify `rejectExtensionOption` handler) +- No path exists to skip signature verification +- Fee deduction cannot be circumvented + +### 2. Validator Management (POA) + +**Entry**: `MsgAddValidator`, `MsgRemoveValidator` transactions + +**Threats**: +- Authority bypass allowing unauthorized validator changes +- Authority address manipulation at initialization +- Validator set corruption leading to consensus failure +- Incorrect token minting/burning during add/remove flows leading to inflation or locked funds +- Wrong pool routing (Bonded vs NotBonded) during validator removal causing state inconsistency +- Incomplete cleanup of delegations/unbondings leaving orphaned state +- Staking hooks (`BeforeValidatorModified`, `BeforeValidatorSlashed`) called in wrong order or swallowed silently +- Edge cases: adding a validator that already has delegations to other validators, removing a validator mid-unbonding + +**Key files**: `x/poa/keeper/keeper.go`, `x/poa/keeper/msg_server_add_validator.go`, `x/poa/keeper/msg_server_remove_validator.go`, `x/poa/types/expected_keepers.go` + +**What to check**: +- `msg.Authority == k.authority` check is present and correct in both handlers +- Authority address is validated (Bech32) at keeper construction +- No alternative code path to modify the validator set +- Genesis state cannot inject unexpected authority +- `ExecuteAddValidator`: coins minted to POA module account and sent to validator, all pre-existing balance/delegation/unbonding checks are exhaustive +- `ExecuteRemoveValidator`: correct pool name used per validator status (BondedPoolName vs NotBondedPoolName), all unbonding delegations slashed before token removal, self-delegation unbonded last +- BankKeeper interactions use correct module names (not arbitrary strings) +- Slash factor of `math.LegacyOneDec()` (100%) is intentional for POA removal + +### 3. EVM Execution + +**Entry**: Ethereum-format transactions via JSON-RPC or Cosmos tx wrapping + +**Threats**: +- EVM sandbox escape +- Incorrect gas accounting between Cosmos and EVM layers +- State inconsistency between EVM and Cosmos views +- Precompile vulnerabilities + +**Key files**: Upstream `cosmos/evm` module (out of scope for deep audit, but check integration points in `app/app.go`) + +**What to check**: +- EVM module is wired with correct ante handlers +- Custom precompiles (if any) are registered correctly +- Gas limit configurations are sane + +### 4. IBC (Inter-Blockchain Communication) + +**Entry**: IBC relayer messages + +**Threats**: +- IBC token transfer manipulation +- Rate limiting bypass +- Channel/port hijacking +- Timeout exploitation + +**Key files**: IBC module wiring in `app/app.go`, rate limiting configuration + +**What to check**: +- Rate limiting module is correctly positioned in the IBC stack +- Transfer channels have appropriate limits configured +- No unprotected IBC ports + +### 5. Configuration & Initialization + +**Entry**: Config files, CLI flags, genesis state + +**Threats**: +- Insecure default values (e.g., TLS disabled, permissive CORS) +- Hardcoded keys or secrets +- Genesis state manipulation +- Environment variable injection + +**Key files**: `cmd/exrpd/cmd/config.go`, `cmd/exrpd/cmd/root.go`, `app/config.go` + +**What to check**: +- Default JSON-RPC/gRPC bindings are not `0.0.0.0` without TLS +- No secrets in source code or default configs +- Custom app config template does not expose sensitive fields +- Address prefixes and coin types match intended values + +### 6. Supply Chain & Infrastructure + +**Entry**: `go.mod`, `Dockerfile`, CI pipelines, GitHub Actions workflows + +**Threats**: +- Compromised Go module dependency +- Dependency confusion attacks +- Build-time secret exposure +- Unpinned base images in Dockerfile +- CI workflow injection via untrusted PR input (`pull_request_target` misuse, expression injection in `${{ }}`) +- Secret leakage in workflow logs or artifacts +- Overly permissive workflow permissions (`contents: write`, `id-token: write`) +- Compromised release pipeline producing tampered binaries +- Missing or insufficient CODEOWNERS coverage on security-sensitive paths + +**Key files**: `go.mod`, `go.sum`, `Dockerfile`, `tools/cosmovisor/Dockerfile`, `Makefile`, `.goreleaser.yml`, `.github/workflows/`, `.github/CODEOWNERS` + +**What to check**: +- All dependencies are pinned to specific versions (not branches) +- `go.sum` is committed and checked +- Dockerfile does not leak SSH keys into the final image (multi-stage build) +- Base images are pinned to digest, not just tag +- GitHub Actions workflows use least-privilege permissions +- No use of `pull_request_target` with checkout of PR code +- Secrets are not interpolated into shell commands (use environment variables instead) +- GoReleaser config produces reproducible builds +- CODEOWNERS requires review for `x/poa/`, `app/ante/`, `app/upgrades/`, `.github/workflows/` + +### 7. Upgrade Handlers + +**Entry**: Chain upgrade proposals triggering state migrations + +**Threats**: +- Malicious or buggy migration logic corrupting state during upgrade +- Non-deterministic migration code causing consensus failure across nodes +- Missing upgrade handler for a scheduled upgrade bricking the chain +- Stale upgrade handlers from previous versions executing unexpectedly +- Upgrade handler accessing or modifying state outside its intended scope + +**Key files**: `app/upgrades/v5/` through `app/upgrades/v10/`, upgrade registration in `app/app.go` + +**What to check**: +- Each upgrade handler is registered exactly once with the correct version name +- Migration logic is deterministic (no maps iterated for state, no goroutines, no time-dependent logic) +- Upgrade handlers only modify state relevant to their version +- No upgrade handler can be re-executed after completion +- Keeper references in upgrade handlers (`app/upgrades/v9/keepers.go`, `app/upgrades/v10/keepers.go`) only expose necessary keepers + +### 8. Governance + +**Entry**: On-chain governance proposals + +**Threats**: +- Governance proposal executing arbitrary module messages (parameter changes, software upgrades, community spend) +- Parameter changes that put the chain in an unsafe state (e.g., unbonding time to 0, max validators to 0) +- Governance bypass via `authz` grants to the gov module account +- POA module exposes `GovKeeper.SubmitProposal` — verify it cannot be abused to self-authorize + +**Key files**: Gov module wiring in `app/app.go`, `x/poa/types/expected_keepers.go` (GovKeeper interface) + +**What to check**: +- Gov module message allowlist is configured (if applicable) to restrict dangerous message types +- Parameter boundaries prevent unsafe values +- `authz` grants cannot escalate to gov-level authority +- POA's GovKeeper interface is minimal and cannot be used to submit arbitrary proposals + +## Cosmos SDK-Specific Concerns + +These are common vulnerability patterns in Cosmos SDK chains that should be checked each audit: + +- **Module account permissions**: Check that module accounts have only the permissions they need. POA module has `Minter` and `Burner` — verify no other module has unexpected mint/burn access. Verify `BondedPoolName` and `NotBondedPoolName` are the only accounts used for staking token burns. +- **Keeper exposure**: Verify keepers are not passed beyond their intended module boundaries. Check `app/app.go` for keepers passed to modules that shouldn't have them. POA receives BankKeeper and StakingKeeper — verify these are the correct scoped interfaces (`x/poa/types/expected_keepers.go`), not the full keeper implementations. +- **Parameter changes**: Check if on-chain parameter changes can lead to unsafe states (e.g., `MaxValidators` to 0 in staking params, unbonding time to 0, bond denom change breaking POA). +- **Non-determinism**: Any use of maps iterated for state, goroutines, or `time.Now()` in state machine code causes consensus failures. Check all code paths in `x/poa/`, `app/ante/`, and `app/upgrades/`. +- **ICA host allow list**: Verify which message types the ICA host module is allowed to execute. An open allow list lets remote chains execute arbitrary messages on this chain. diff --git a/.claude/skills/security-audit/SKILL.md b/.claude/skills/security-audit/SKILL.md new file mode 100644 index 0000000..3032d06 --- /dev/null +++ b/.claude/skills/security-audit/SKILL.md @@ -0,0 +1,23 @@ +--- +name: security-audit +description: Run a full security audit across all focus areas in parallel, reporting findings to peersyst/security +disable-model-invocation: true +allowed-tools: Bash(gh *) Read Grep Glob Agent +--- + +# Security Audit + +Read `.claude/security/SECURITY_SCOPE.md` and `.claude/security/THREAT_MODEL.md`. Then spawn one `security-reviewer` agent per focus area defined in the "Audit Focus Areas" table, running them all in parallel. + +Each agent should: + +1. Query existing issues first: + ```bash + gh issue list -R peersyst/security --label "repo:xrplevm/node" --state all --json number,title,labels,state + ``` +2. Audit its assigned area by reading the components listed in scope +3. For each new finding, create an issue in `peersyst/security` following the reporting workflow in SECURITY_SCOPE.md (labels: `repo:xrplevm/node`, severity, `pending`; area goes in issue body) +4. Skip any finding that already exists as `pending`, `accepted`, or `discarded` +5. For closed (done) findings, verify the fix is still in place — reopen only if regressed + +After all agents complete, summarize the total findings created per area. diff --git a/.claude/skills/security-issue/SKILL.md b/.claude/skills/security-issue/SKILL.md new file mode 100644 index 0000000..a9544ab --- /dev/null +++ b/.claude/skills/security-issue/SKILL.md @@ -0,0 +1,69 @@ +--- +name: security-issue +description: Create a security finding in the private peersyst/security repo with proper labels and format. Use when reporting a security vulnerability, concern, or observation found during audits or ad-hoc review. +disable-model-invocation: true +allowed-tools: Bash(gh *) Read Grep +--- + +# Security Issue Skill + +Create a security finding in `peersyst/security`. Gather the following information from the user or from context: + +1. **Severity**: One of `critical`, `high`, `medium`, `low`, `info` +2. **Area**: The focus area (e.g., POA module, Authorization & access control, EVM integration, IBC & cross-chain, etc.) +3. **Title**: Short description of the finding +4. **Location**: File path and line numbers +5. **Finding**: Description of the vulnerability or concern +6. **Impact**: What could go wrong and under what conditions +7. **Recommendation**: Suggested fix or mitigation +8. **Evidence**: Code snippets, reasoning, or proof of concept (optional) + +If any required field is missing, ask the user before proceeding. + +## Before creating + +Check for duplicates first: + +```bash +gh issue list -R peersyst/security --label "repo:xrplevm/node" --state all --json number,title,labels,state -q '.[] | select(.title | test("KEYWORD"; "i"))' +``` + +Replace KEYWORD with a relevant term from the title. If a duplicate exists, inform the user and ask whether to proceed. + +## Create the issue + +```bash +gh issue create -R peersyst/security \ + --title "[SEVERITY_UPPER] Title here" \ + --label "repo:xrplevm/node,SEVERITY,pending" \ + --body "$(cat <<'EOF' +## Area + + + +## Finding + + + +## Location + + + +## Impact + + + +## Recommendation + + + +## Evidence + + +EOF +)" +``` + +## After creating + +Report the issue URL back to the user. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..1400c70 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,53 @@ +# CLAUDE.md + +## Project Overview + +XRPL EVM Sidechain node (`exrpd`) — a Cosmos SDK-based blockchain node that runs an EVM-compatible sidechain for the XRP Ledger. Uses Proof-of-Authority consensus with authority-gated validator management. + +## Build & Test + +```bash +make build # Build the exrpd binary +make test # Run unit tests +make lint # Run linter +go vet ./... # Vet all packages +``` + +## Project Structure + +``` +cmd/exrpd/ # CLI entry point and node configuration +app/ # Cosmos SDK app wiring, ante handlers, upgrade handlers +app/ante/ # Transaction validation (routes EVM vs Cosmos txs) +x/poa/ # Proof-of-Authority module (validator add/remove) +proto/ # Protobuf definitions (gRPC API surface) +types/ # Core types (address prefixes, denominations) +testutil/ # Test helpers +tests/ # Integration tests +security/ # Security audit scope and threat model +``` + +## Security Audits + +This repo is configured for monthly AI-assisted security audits. Before performing any security-related review, read: + +1. **`.claude/security/SECURITY_SCOPE.md`** — Defines what to audit, trust boundaries, priority tiers, and focus areas. +2. **`.claude/security/THREAT_MODEL.md`** — Assets, adversary profiles, attack surfaces, and Cosmos SDK-specific vulnerability patterns. + +### Running an audit + +Spawn one `security-reviewer` agent per focus area defined in SECURITY_SCOPE.md. Findings are reported as issues in the **private** `peersyst/security` repo with `repo:xrplevm/node` label. Before reporting, query existing issues to avoid duplicates. + +``` +Read .claude/security/SECURITY_SCOPE.md and .claude/security/THREAT_MODEL.md. Then perform a security audit focused on: [AREA]. Check the components listed in the scope. Report findings to peersyst/security following the reporting workflow in SECURITY_SCOPE.md. +``` + +### Key security invariants + +These must always hold and should be verified in every audit: + +- **Authority gate**: `x/poa` message handlers must check `msg.Authority == k.authority` before any validator set mutation. +- **Ante handler routing**: EVM and Cosmos transactions must be routed to their respective handler chains with no bypass path. +- **Extension option rejection**: Unknown extension options must be rejected by the ante handler. +- **No non-determinism in state machine**: No maps iterated for state, no goroutines, no `time.Now()` in consensus code. +- **IBC rate limiting**: The rate limiting module must be in the IBC middleware stack.