SybilShield-Core is an open-source, modular framework that detects and isolates Sybil identities in permissionless peer-to-peer blockchain networks. A Composite Trust Score fuses behavioral telemetry, peer-graph topology, and economic commitment, no Proof-of-Work tax, no centralized identity authority, just observable evidence governing each peer's influence on consensus.
The numbers below are from a real, runnable simulation harness added to this repo
(scripts/run_simulation.py) — not the earlier placeholder claims.
See the disclosure in Benchmark results for exact scale and caveats.
Sybil resistance is not a niche blockchain concern, it is the structural assumption that "one peer, one vote" depends on. The same identity-spoofing pattern underwrites attacks on decentralized federated learning, oracle price feeds, and any system that trusts the apparent diversity of its participants. A framework that closes this gap without reintroducing a central authority strengthens the integrity of decentralized infrastructure that increasingly underpins finance, identity, and shared AI training.
CTSEngine's quarantine flag is currently a one-way latch: once a peer's score crosses the 0.20 threshold it stays quarantined even if the score later recovers. Automatic reinstatement is a known gap, not yet implemented.scripts/run_simulation.py), and unit tests are public, so detection-rate and overhead claims can be independently re-run and verified.Three independently maintained sub-scores combine into one Composite Trust Score (CTS) per peer, which then governs quorum weight and connection acceptance. A federated-learning aggregation weighting layer is part of the paper's design and has a wired event type (oracle_deviation), but is not yet implemented as a standalone module in this repo.
Continuously updated from block relay timing, mempool propagation, and voting deviations. Decays toward neutral with a 24-hour half-life, so static whitelisting is impossible: inactive peers must keep demonstrating good behavior.
Derived from local clustering coefficient, SybilRank propagation from high-stake seed nodes, and subnet diversity. Penalizes the tight-cluster topology characteristic of Sybil subgraphs without requiring a certified honest seed set. Measured in this repo's harness to contribute at most ±10% of a peer's score — on its own it is not strong enough to quarantine a behaviorally-dormant Sybil.
Stake age is recorded per peer, but as measured in this benchmark CTSEngine's own scoring path does not currently read it automatically; the only economic lever exercised is the existing stake_age_bonus reward event, applied explicitly by the simulation harness rather than derived internally from stake age.
A sigmoid mapping turns the composite score into quorum weight. Four response tiers, monitoring, throttling, peer-list removal, and full quarantine, apply escalating pressure as the score drops. As measured, quarantine in the reference engine is currently one-way (no automatic reinstatement even if the score later recovers) — see the disclosure in Benchmark results.
Evaluated by actually driving the four scripted attack scenarios below through the real detection pipeline (n=300 honest nodes, 20 trials per density, 10/20/30% Sybil density — see Benchmark results). This is a smaller scale than the 50-2,000 node / 10-45% range originally asserted here; that claim was never backed by a runnable simulation.
| Attack class | SybilShield-Core defense | Measured (active adversary) |
|---|---|---|
| Consensus masking | Repeated relay-timeout penalties (0.05/event) via the real BehaviorMonitor.record_relay() threshold check drive quorum weight down | 100% TPR, 0% FPR; median 6 rounds to quarantine |
| Eclipse partitioning | IsolationGuard subnet-diversity and per-subnet connection limits reject monopolizing connection attempts independent of the CTS | 27.5% of Sybil attack-edge connection attempts rejected outright (110/400); behavioral quarantine at median round 0 |
| DFL gradient poisoning | An anomalous update fires the oracle_deviation penalty event, which this benchmark drives directly through CTSEngine | 100% TPR, 0% FPR on the event-detection path only — no FL aggregation module or model-accuracy benchmark exists in this repo (see disclosure) |
| Mempool / bandwidth exhaustion | Sliding-window flood detection in the real BehaviorMonitor.record_transaction_broadcast() (>50 tx / 10s) triggers penalties | 100% TPR, 0% FPR; median <1 round (burst typically fires the threshold multiple times in round 0) |
All "measured" figures above are for the fully active adversary condition (intensity=1.0). With half the Sybil population behaviorally dormant (intensity=0.5), detection drops to ~48-51% across all four scenarios — see Benchmark results.
python scripts/run_simulation.py.
| Metric | Composite CTS (this repo) | Graph-only baseline |
|---|---|---|
| TPR, active adversary, all densities | 100.0% | 65.9–100.0% (density-dependent, see note) |
| FPR, active adversary, all densities | 0.00% | 0.0–11.0% (density-dependent, see note) |
| TPR, half-dormant Sybil population | ~48–51% | 65.9–100.0% |
| Median detection latency (rounds) | 0–6 (attack-type dependent) | n/a (single snapshot, no latency concept) |
| IsolationGuard eclipse-edge rejection | 27.5% (110/400) | n/a |
| Per-connection compute overhead | 76.14 µs (vs. 0.068 µs no-op) | n/a |
The graph-only baseline is a simplified SybilRank-style detector (flags the bottom 20th percentile of nodes by propagated trust) run on the identical generated topology — not a reimplementation of SybilGuard or SybilLimit's random-walk protocol. Its TPR/FPR move mechanically with density because its flagging quota is fixed at 20% of all nodes: at 10% Sybil density it over-flags honest peers to fill the quota (11.0% FPR); at 30% density it structurally cannot flag more than 20/30 ≈ 66.7% of the true Sybils. This is a property of the fixed-quota baseline, not evidence that graph-only detection "gets harder" at scale in some deeper sense.
The half-dormant condition exists because CTSEngine.update_centrality() contributes at most ±10% to a peer's score (a constant in cts_engine.py) — on its own that is not enough to push a Sybil that never behaves maliciously from the neutral starting score (0.5) down to the 0.20 quarantine threshold. A dormant Sybil is, on this evidence, detected only if it also happens to trip a behavioral penalty.
Python 3.10+ is the only prerequisite.
git clone https://github.com/sunilgentyala/SybilShield-Core.git
cd SybilShield-Core
pip install -e ".[dev]"
# Run the real detection-pipeline simulation (writes a full report to
# simulation/results/sybil_detection_results.txt)
python scripts/run_simulation.py --nodes 300 --trials 20 \
--sybil-ratios 0.10,0.20,0.30 --scenario all --intensities 1.0,0.5
# Run unit + simulation tests
pytest tests/unit/ tests/simulation/ -v