bridge-security-toolkit

Security analysis toolkit for cross-chain bridge protocols. Analyzes validator sets, admin key management, timelock configurations, proxy upgradeability, rate limiting, and message verification across major bridge implementations.

Architecture

bridge-security-toolkit/
├── src/
│   ├── analyzers/          # Protocol-agnostic security analyzers
│   │   ├── validatorSet    — DVN/guardian/validator set analysis
│   │   ├── timelock        — Timelock delay & role analysis
│   │   ├── adminKeys       — Ownership chain & multisig analysis
│   │   ├── upgradeability  — Proxy pattern detection (transparent/UUPS/beacon/diamond)
│   │   ├── rateLimiter     — Rate limit detection
│   │   ├── messageVerification — Message verification pathway analysis
│   │   └── governance      — Governance event timeline builder
│   ├── bridges/            # Protocol-specific analyzers
│   │   ├── layerzero       — V1 ULN + V2 DVN configuration analysis
│   │   ├── wormhole        — Guardian set & quorum analysis
│   │   ├── axelar          — Validator set & gateway analysis
│   │   ├── hyperlane       — ISM tree analysis (multisig/routing/aggregation)
│   │   ├── ccip            — Chainlink CCIP router & lane analysis
│   │   ├── arbitrum        — Native bridge inbox/outbox analysis
│   │   └── adapter         — Plugin adapter registry
│   ├── chain/              # Chain interaction utilities
│   │   ├── provider        — Multi-chain provider management
│   │   ├── multicall       — Batched contract reads
│   │   └── contracts       — Known contract addresses
│   ├── report/             # Report generation
│   │   ├── generator       — Markdown/JSON/summary report output
│   │   └── scoring         — Weighted security scoring engine
│   ├── utils/              — ABIs, addresses, logging
│   ├── alerts              — Critical finding detection & alerting
│   ├── batch               — Batch analysis across multiple chains
│   ├── compare             — Multi-bridge comparison mode
│   └── index               — CLI entry point & library exports
├── test/                   # Vitest unit tests
├── examples/               # Usage examples
└── .github/workflows/      # CI configuration

Supported Bridges

Bridge	Version	Analysis Depth
LayerZero	V1 + V2	ULN oracle/relayer, DVN required/optional sets, per-OApp config
Wormhole	V1	Guardian set size, quorum threshold, guardian key analysis
Axelar	V1	Gateway admin threshold, auth weight verification
Hyperlane	V3	Full ISM tree — MultisigISM, RoutingISM, AggregationISM, NullISM
Chainlink CCIP	V1	Router configuration, on/off-ramp analysis
Arbitrum	Native	Inbox/outbox configuration, rollup admin analysis

Analyzers

Analyzer	What It Checks
validatorSet	Number of validators/DVNs, required threshold, single-point-of-failure detection
timelock	Min delay, zero-delay detection, role analysis (proposer/executor/admin)
adminKeys	Ownership chain resolution, EOA vs multisig, Safe threshold/guard/modules
upgradeability	EIP-1967 proxy detection, UUPS/transparent/beacon/diamond, implementation init check
rateLimiter	Rate limit configuration, window duration, max amount per window
messageVerification	Message verification pathway, ISM configuration depth
governance	Historical event timeline: upgrades, ownership transfers, delay changes
oapp	LayerZero V2 OApp delegate, peer config, enforced options analysis
messageFlow	Cross-chain message lifecycle tracing (send → verify → execute)
upgradeHistory	Proxy upgrade history reconstruction from on-chain events

Installation

npm install
npm run build

Usage

CLI

# Analyze a bridge protocol
npx ts-node src/index.ts analyze -p layerzero -c 1

# Analyze with custom RPC
npx ts-node src/index.ts analyze -p wormhole -c 1 -r https://eth.llamarpc.com

# Analyze a specific OApp's DVN configuration (LayerZero V2)
npx ts-node src/index.ts analyze -p layerzero -c 1 --oapp 0xYourOAppAddress

# Check admin/ownership chain
npx ts-node src/index.ts check-admin -a 0xContractAddress -c 1

# Check proxy upgradeability
npx ts-node src/index.ts check-proxy -a 0xContractAddress -c 1

# Output as Markdown
npx ts-node src/index.ts analyze -p layerzero -c 1 -o markdown > report.md

Library

import {
  ChainProviderManager,
  LayerZeroAnalyzer,
  AdminKeyAnalyzer,
  SecurityScorer,
  ReportGenerator,
} from 'bridge-security-toolkit';

const provider = new ChainProviderManager({
  1: 'https://eth.llamarpc.com',
});

const client = provider.getClient(1);
const lz = new LayerZeroAnalyzer(client);

// Analyze V1 endpoint
const v1 = await lz.analyzeV1(1);

// Analyze V2 OApp DVN config
const v2 = await lz.analyzeV2OApp('0xOAppAddress', 1, [30101, 30110]);

// Score findings
const score = SecurityScorer.calculate([...v1.findings, ...v2.findings]);
console.log(`Score: ${score.overall}/100`);

Security Scoring

The scoring engine evaluates six categories with weighted importance:

Category	Weight	What Lowers Score
Validator Security	25%	Low validator count, 1-of-1 DVN, single oracle
Admin Key Management	20%	EOA owner, 1-of-N multisig, no guard
Message Verification	20%	NullISM, weak ISM config, missing verification
Timelock Protection	15%	No timelock, zero delay, very short delay
Upgradeability Safety	10%	Uninitialized implementation, complex proxy chains
Rate Limiting	10%	No rate limits, very high limits

Critical findings cap the overall score at 30/100 maximum. High findings cap at 60/100.

Development

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint
npm run lint

License

MIT