Skip to content

Add Claude Code security review rules for Bor codebase#2110

Merged
adamdossa merged 3 commits intodevelopfrom
add-claude-security-rules
Mar 9, 2026
Merged

Add Claude Code security review rules for Bor codebase#2110
adamdossa merged 3 commits intodevelopfrom
add-claude-security-rules

Conversation

@mt-polygon-technology
Copy link
Copy Markdown
Contributor

@mt-polygon-technology mt-polygon-technology commented Mar 5, 2026

Description

Add path-scoped security review rules for Claude Code that enable automated security-aware code review across all critical areas of the Bor codebase. Each rule file defines a threat model, critical invariants, patterns to flag with severity levels, and a review checklist — scoped to specific source paths so rules activate only on relevant diffs.

Rules are informed by production incident lessons (e.g. RLP cross-client mismatch with Erigon, Heimdall desync cascading failures) and include a threat source classification system that escalates severity when bugs are externally triggerable (by peers, RPC users, or validators).

Updated CLAUDE.md with Bor vs upstream geth architectural differences and a reference table linking each rule to its covered paths.

Changes

  • Bugfix (non-breaking change that solves an issue)
  • Hotfix (change that solves an urgent issue, and requires immediate attention)
  • New feature (non-breaking change that adds functionality)
  • Breaking change (change that is not backwards-compatible and/or changes current functionality)
  • Changes only for a subset of nodes

Files added/modified

11 new rule files in .claude/rules/:

Rule Covers
security-common.md Severity framework, threat source multiplier, global Go patterns
consensus-security.md Bor PoA consensus, block production, Heimdall interaction, PIP-66
blockchain-security.md Chain insertion, reorgs, fork choice, genesis, RLP, rawdb
evm-security.md Opcodes, gas accounting, precompiles, BlockSTM interaction
state-security.md Account state, MPT, BlockSTM parallel execution, MVHashMap
contract-interaction-security.md ABI encoding, system contracts, state sync, return validation
crypto-security.md Key management, signature verification, hashing
p2p-security.md Peer management, message handling, DoS protection
rpc-security.md API exposure, resource limits, bor_* namespace, batch limits
txpool-security.md Transaction validation, pool management, eviction
eth-backend-security.md eth/ backend, fetcher, filters, catalyst, database layers

Updated: CLAUDE.md — added Bor-specific context and rules reference table.

Checklist

  • I have added at least 2 reviewer or the whole pos-v1 team
  • I have added sufficient documentation in code
  • I will be resolving comments - if any - by pushing each fix in a separate commit and linking the commit hash in the comment reply
  • Created a task in Jira and informed the team for implementation in Erigon client (if applicable)
  • Includes RPC methods changes, and the Notion documentation has been updated

Cross repository changes

  • This PR requires changes to heimdall
  • This PR requires changes to matic-cli

Testing

  • I have added unit tests
  • I have added tests to CI
  • I have tested this code manually on local environment
  • I have tested this code manually on remote devnet using express-cli
  • I have tested this code manually on amoy
  • I have created new e2e tests into express-cli

Manual tests

Tested by running claude -p against recent PRs (#2092, #2094) and verifying that:

  1. Rules load correctly and activate based on file paths in the diff
  2. Security findings reference the correct rule and severity classification
  3. Threat source (external vs self-inflicted) is correctly identified

Additional comments

This PR adds no runtime code — only .claude/rules/*.md and CLAUDE.md changes. Zero impact on Bor binary or behavior.

@codecov
Copy link
Copy Markdown

codecov bot commented Mar 5, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 51.39%. Comparing base (ba46e15) to head (8a327ce).
⚠️ Report is 14 commits behind head on develop.

Additional details and impacted files

Impacted file tree graph

@@             Coverage Diff             @@
##           develop    #2110      +/-   ##
===========================================
+ Coverage    51.22%   51.39%   +0.17%     
===========================================
  Files          878      881       +3     
  Lines       152444   152810     +366     
===========================================
+ Hits         78084    78535     +451     
+ Misses       69264    69170      -94     
- Partials      5096     5105       +9

see 49 files with indirect coverage changes
see 49 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@marcello33 marcello33 requested a review from a team March 5, 2026 15:20
mt-polygon-technology and others added 3 commits March 9, 2026 16:05
@mt-polygon-technology @adamdossa
Add Claude security rules and update CLAUDE.md
611ee91 
Add path-scoped security review rules for Claude Code covering consensus,
crypto, P2P, RPC, EVM, state, txpool, blockchain, contract interactions,
and eth backend. Update CLAUDE.md with Bor vs geth differences and
security rules reference table.
@mt-polygon-technology @adamdossa
claude/rules: production feedback, threat source classification, cros…
5eb9550 
…s-client parity

Incorporate real-world incident lessons and threat modeling improvements:

Production feedback:
- RLP encoding consistency across tx types and clients (Erigon incident)
- Heimdall desync as network-level incident, not just missed checkpoints
- PIP-66 early announcement context for block time enforcement
- Precompile lifecycle in contracts.go: init(), ActivePrecompiles, HF gating
- Cross-client parity requirement for precompile changes (Bor <> Erigon)
- BlockSTM serial/parallel not mutually exclusive
- RPC batch data limits (hardcoded max or config)

Threat source classification:
- Add external vs self-inflicted severity multiplier to security-common.md
- Add Trigger column (Peer/RPC User/Validator/Self) to pattern tables
- Escalate externally-triggerable patterns by one severity level
- Mark self-inflicted patterns to avoid over-prioritizing during review
@adamdossa
Give Claude PR write ability
96b347e
@adamdossa adamdossa force-pushed the add-claude-security-rules branch from 8a327ce to 96b347e Compare March 9, 2026 16:06
@adamdossa adamdossa merged commit 6da722f into develop Mar 9, 2026
9 of 12 checks passed
@sonarqubecloud
Copy link
Copy Markdown

sonarqubecloud bot commented Mar 9, 2026

Quality Gate Passed Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@adamdossa adamdossa adamdossa approved these changes

@marcello33 marcello33 marcello33 approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@mt-polygon-technology @adamdossa @marcello33