Genesis poisoning:fix/hardening docker entrypoint

[greenarmor]

Security Assessment Summary

This document captures the primary security weaknesses identified during the review and the remediation steps implemented in this change-set. A hands-on proof-of-concept that recreates the original vulnerability and demonstrates the hardened mitigation is available in docs/poc/genesis_poisoning.md.

1. Insecure Genesis File Bootstrap

Issue

• Both the Docker entrypoint (docker-entrypoint.sh) and the volunteer helper script (scripts/join-as-volunteer.sh) downloaded the network genesis file directly from the main branch without integrity checks.
• The downloads used silent curl invocations that ignored HTTP errors and offered no tamper detection. Any man-in-the-middle attack, compromised CDN, or unexpected upstream change could silently deliver a malicious genesis file. A poisoned genesis file allows an attacker to modify the validator set or bootstrap nodes onto a hostile fork.

Remediation

• Added strict download options (curl -fSL --retry 3 --retry-delay 2) so HTTP failures surface immediately.
• Introduced optional GENESIS_URL and GENESIS_SHA256 overrides and checksum verification in both scripts.
• Added dependency checks for curl, jq, and sha256sum to fail fast when prerequisites are missing.
• Hardened scripts with set -euo pipefail, temporary-file handling, and cleanup traps to avoid partial writes.

Operator Action Items

• Publish an official GENESIS_SHA256 alongside every release and configure the environment variables (or script arguments) accordingly.
• When hosting alternative genesis mirrors, ensure the checksum matches the canonical release artifact.
• Consider pinning GENESIS_URL to an immutable tag or release asset rather than a moving branch reference.

2. General Operational Guidance

• Monitor CI/CD pipelines to ensure scripts remain executable and dependencies such as jq and sha256sum stay available in container images.
• Document the expected checksum management process in validator onboarding materials so volunteers consistently verify genesis integrity.

The combination of these mitigations closes the immediate loophole around silent genesis tampering and establishes a clearer operational posture for secure node provisioning.

[greenarmor]

Genesis Poisoning Proof-of-Concept

This walkthrough demonstrates how the original bootstrap process (prior to the
hardened changes in docker-entrypoint.sh and scripts/join-as-volunteer.sh)
could be subverted by serving a tampered genesis.json. It also shows how the
new checksum enforcement blocks the attack.

⚠️ This PoC is for educational and regression-testing purposes. Do not run
it on production nodes.

Prerequisites

• bash
• curl
• python3
• sha256sum

All of these tools are pre-installed in the development container.

Running the PoC

./genesis_poisoning.sh

What the script does

1. Generates a "legitimate" genesis file (govchain) and an attacker-controlled
   variant (shadowchain).
2. Hosts the malicious file on http://127.0.0.1:9854/genesis.json using
   python3 -m http.server to emulate a compromised mirror or man-in-the-middle
   proxy.
3. Performs an "insecure" download that mirrors the behavior of the legacy
   scripts (no checksum validation) and prints the poisoned chain ID that would
   silently pivot nodes onto the wrong fork.
4. Replays the download but verifies it against the published SHA-256 of the
   legitimate genesis. The checksum mismatch terminates the flow, illustrating
   how the hardened scripts protect operators once a checksum is published and
   enforced.

Expected output

=============================
Genesis Poisoning Proof-of-Concept
=============================

[1] Simulating the pre-hardened bootstrap (no checksum verification)...
 Downloaded chain-id: shadowchain

This is the attacker-controlled chain identifier. Prior to the hardened scripts,
the bootstrap process would have accepted this file without any alarms, and the
node would join the shadow chain.

[2] Enforcing the published checksum to block the attack...
<...sha256sum failure details...>

  Checksum validation failed as expected. When operators publish the canonical
   SHA-256 and the hardened scripts enforce it, the tampered genesis file is
   rejected before initialization.

If you do not see the checksum failure, ensure no other process is bound to
port 9854 and rerun the script.

What does the attacker gain?

The genesis.json file acts as the network's birth certificate: it defines the
chain ID, validator set, and the initial state hash that every honest node will
trust. If an attacker convinces your bootstrap process to accept their forged
genesis, your node will happily initialize a different blockchain—the
attacker's shadow chain. From there the attacker can:

• Point you at validator keys they control, so every block you follow comes
  from their infrastructure instead of the legitimate network.
• Keep you fenced inside their fork even though you share the same physical
  network or data center as honest peers; your node's handshake will reject the
  real chain because the chain IDs no longer match.
• Rewrite balances or governance parameters in the altered genesis, effectively
  isolating you on a counterfeit ledger that looks valid from your node's point
  of view.

This is why checksum validation is essential: it is the only way for a node to
prove that the "treasure map" it downloaded really matches the one published by
the community. Without the patch, nothing stops an attacker on the same LAN, a
compromised mirror, or a malicious Wi-Fi hotspot from handing out their own
shadow chain.

How a man-in-the-middle fools a new operator

1. The new operator fetches the genesis over an insecure channel. The legacy
   bootstrap scripts perform a plain HTTP curl to a mirror or community host
   such as http://bootstrap.example.org/genesis.json.
2. The attacker inserts themselves between the operator and the mirror. On
   a shared Wi-Fi network they can ARP-spoof the victim, poison DNS, or operate
   a captive portal that silently proxies all HTTP requests.
3. The forged response is delivered first. Because HTTP lacks integrity
   protection, the attacker replies with their shadowchain genesis before the
   real server's packet arrives (or simply drops the legitimate response).
4. The legacy script trusts the bogus file. Without a published checksum or
   signature to compare against, the script happily saves the malicious
   genesis.json and initializes the node. From that moment on, the new
   operator is stranded on the attacker's shadow chain despite being on the same
   physical network as the real one.

The hardened workflow blocks step 4 by requiring the downloaded file to match
the community-published SHA-256. A man-in-the-middle can still intercept the
traffic, but they cannot forge a file that passes checksum validation without
also compromising the channel where the checksum is distributed.

ELI5: What happens if the fix is missing?

Imagine you're copying a treasure map from a friend. If you never check whether
the map is really from your friend, a trickster can slip you a fake map that
points to their cave instead. The original bootstrap scripts were just like
that: they grabbed whatever genesis.json file arrived first, so a bad actor
could quietly hand over a forged map and your node would follow the wrong
chain.

The hardened patch makes you compare the map to a known-good fingerprint before
you trust it. When the checksum doesn't match, the script stops immediately so
the trickster's fake map never gets used. Without that checksum step, nodes stay
blind to the swap and march straight into the attacker's network.