tibet-mirror 0.1.0

Verified Package Mirror — TIBET provenance for package mirrors, supply chain attack detection

tibet-mirror — Verified Package Mirror with TIBET Provenance

Every mirrored package gets a TIBET token proving: when it was mirrored, from where, and its hash at mirror time.

If upstream changes (supply chain attack), the TIBET chain breaks. The mirror refuses the package.

tibet-mirror is an enterprise-grade package mirror (PyPI, npm) with supply chain attack detection. Every package that enters your mirror is stamped with a TIBET provenance token. If the upstream registry silently replaces a package, the hash mismatch breaks the TIBET chain and your mirror rejects it.

The Supply Chain Attack Problem

Package registries like PyPI and npm are high-value targets. An attacker who compromises an upstream package can inject malicious code into thousands of downstream systems.

[Upstream PyPI]                         [Your Mirror]
  requests==2.31.0                        requests==2.31.0
  sha256: abc123...                       mirror_hash: abc123...
        |                                 tibet_token: jis:mirror:...
        v                                        |
  ATTACKER replaces package!              tibet-mirror compares:
  sha256: def456... (malicious)             source_hash != mirror_hash
        |                                   TIBET chain BROKEN
        v                                        |
  Mirror pulls update...                  --> QUARANTINE. Alert.

Install

pip install tibet-mirror

With Bandersnatch integration:

pip install tibet-mirror[bandersnatch]

Quick Start

from tibet_mirror import MirrorEngine, MirrorPolicy

engine = MirrorEngine(mirror_node="mirror-eu-01")

# Mirror a package — creates TIBET provenance token
record = engine.mirror_package(
    name="requests",
    version="2.31.0",
    source_url="https://pypi.org/simple/requests/",
    package_hash="abc123def456...",
)

print(record.verified)       # True
print(record.tibet_token_id) # "jis:mirror:a1b2c3d4..."

# Later: verify the package still matches upstream
result = engine.verify_package("requests", "2.31.0")
print(result)  # True — hashes still match

# Full integrity check across all mirrored versions
integrity = engine.check_integrity("requests")
print(integrity.drift_detected)  # False — no supply chain drift

# Add a policy: block packages with known CVEs
engine.add_policy(MirrorPolicy(
    name="block-known-cves",
    action="BLOCK",
    conditions={"has_cve": True, "severity": "critical"},
    description="Block packages with critical CVEs",
))

CLI

tibet-mirror info       # Concept overview and supply chain attack scenario
tibet-mirror demo       # Demo: mirror packages, detect simulated attack
tibet-mirror policies   # Show default mirror policies
tibet-mirror status     # Mirror statistics

How It Works

1. Mirror — Package is downloaded from upstream (PyPI/npm)
2. Hash — SHA-256 of the package at mirror time
3. TIBET Token — Provenance token records: who mirrored, when, from where, hash
4. Verify — On every sync, compare upstream hash with mirror hash
5. Detect — If hashes diverge, the TIBET chain breaks. Package is quarantined.

TIBET Provenance Layers

Every mirrored package creates a TIBET token:

Layer	Content
ERIN	Package name, version, source + mirror hashes
ERAAN	Source registry URL, upstream hash at mirror time
EROMHEEN	Mirror node, timestamp, operator
ERACHTER	Mirror reason (scheduled sync, manual, policy override)

The token chain proves exactly which packages were mirrored when, and whether they have been tampered with since.

Mirror Policies

Policy	Action	Description
verify-on-sync	MIRROR	Always verify hash before accepting upstream update
block-known-cves	BLOCK	Refuse packages with known critical CVEs
quarantine-new	QUARANTINE	Hold first-time packages for manual review
block-typosquat	BLOCK	Refuse packages with names similar to popular packages

Bandersnatch Integration

tibet-mirror integrates with Bandersnatch, the official PyPI mirror tool:

from tibet_mirror import MirrorEngine

engine = MirrorEngine(mirror_node="bandersnatch-eu-01")

# After Bandersnatch syncs a package, create provenance
record = engine.mirror_package(
    name="django",
    version="5.0.1",
    source_url="https://pypi.org/simple/django/",
    package_hash="...",
)

# Scan for upstream drift
drift = engine.scan_upstream("django")
print(drift)  # PackageIntegrity showing any version mismatches

Part of the TIBET ecosystem

Package	Purpose
tibet-core	Protocol core
tibet-y2k38	Y2K38 Time Bridge
tibet-pol	Process Integrity Checker
tibet-pqc	Post-Quantum Crypto Router
tibet-overlay	Identity Overlay
tibet-twin	Digital Twin Guard
tibet-mirror	Verified Package Mirror

License

MIT — Humotica AI Lab 2025-2026

Authors

• J. van de Meent — [e-mail]
• R. AI (Root AI) — [e-mail]