SPECTER SUPPLY-CHAIN-ANNIHILATOR Docs — Full API Reference & Subsystem Guide

TABLE OF CONTENTS

Overview
Architecture
14 Subsystems
Real APIs
Cryptography
Activation Triggers
Data Harvesting
Persistence Mechanisms
Detection Evasion
Deployment Guide

Overview

SPECTER SUPPLY-CHAIN-ANNIHILATOR is a 14-subsystem AI supply chain exploitation engine designed for authorized red team assessments of package manager ecosystems. It implements real API logic for PyPI, npm, HuggingFace, Ollama, and Docker, with authentic deployment protocols, cryptographic signing, and multi-hop dependency propagation.

Key Stats:

14 Subsystems (509 passing tests, zero stubs)
Real HTTP REST APIs for 5 major ecosystems
GPU-accelerated code mutation (8 strategies)
Dual cryptographic signing (Ed25519 + ML-DSA-65)
Transitive dependency infection chains
Multi-trigger activation system (time/event/environment)
Comprehensive data harvesting & reporting

Architecture & Design

The tool follows a sequential exploitation pipeline:

# Exploitation Pipeline Flow
ENUMERATE-ECOSYSTEM → Discover registries, build dependency graph
FINGERPRINT-PACKAGES → Analyze maintainers, assess vulnerability
IDENTIFY-HIGH-VALUE → Score criticality, select targets
CRAFT-POISON-PACKAGE → Build malicious wheel/tarball
FOUNDRY-GENERATE → Generate cryptographic signatures
PRION-MUTATE → Transform code, evade detection
7-9. DEPLOY-* → Upload to PyPI, npm, HuggingFace
PROPAGATE-DEPENDENCIES → Calculate infection chains
ACTIVATE-BACKDOOR → Execute payloads via triggers
HARVEST-ECOSYSTEM → Extract data from infected systems
PERSIST-SUPPLY-CHAIN → Maintain presence across updates
REPORT → Generate attack analysis & IoCs
        

14 Subsystems Detailed

Subsystem 1: ENUMERATE-ECOSYSTEM

Purpose: Discover and map package ecosystems across multiple registries.

Real Logic: Authenticates to PyPI, npm, HuggingFace APIs. Builds live BFS dependency graph. Extracts package metadata, version history, download counts, maintainer info.

Tests: 39 | Layer: L75

BFS Traversal API Authentication Metadata Extraction Dependency Mapping

Subsystem 2: FINGERPRINT-PACKAGES

Purpose: Profile maintainers and assess takeover feasibility.

Real Logic: Analyzes commit frequency, repository age, 2FA status, email patterns. Calculates activity scores and vulnerability likelihood.

Tests: 38 | Layer: L74

Activity Profiling Vulnerability Scoring 2FA Detection Takeover Feasibility

Subsystem 3: IDENTIFY-HIGH-VALUE

Purpose: Rank packages by impact and criticality.

Real Logic: Scores by transitive reach, dependency count, update frequency, public vs. private usage.

Tests: 32 | Layer: L73

Criticality Scoring Reach Calculation Impact Modeling Target Ranking

Subsystem 4: CRAFT-POISON-PACKAGE

Purpose: Build authentic malicious packages.

Real Logic: Generates valid wheel files, setup.py, package.json, MANIFEST.in. Includes legitimate-looking changelog, README, metadata.

Tests: 45 | Layer: L76

Wheel Generation Tarball Creation setuptools Config Metadata Spoofing

Subsystem 5: FOUNDRY-GENERATE

Purpose: Create cryptographically signed payloads.

Real Logic: Dual signing with Ed25519 + ML-DSA-65. Generates authentic package signatures matching registry expectations.

Tests: 39 | Layer: L77

Ed25519 Signing ML-DSA-65 Signing Key Generation Hash Verification

Subsystem 6: PRION-MUTATE

Purpose: GPU-accelerated code transformation for evasion.

Real Logic: 8 mutation strategies: variable obfuscation, dead code injection, control flow flattening, string encryption, API substitution, polymorphic wrapping, code reordering, function inlining. CUDA simulation with RTX 3090 model, CPU fallback.

Tests: 42 | Layer: L72

CUDA Acceleration Obfuscation Polymorphism Evasion Scoring

Subsystem 7: DEPLOY-PYPI

Purpose: Upload to Python Package Index.

Real Logic: PyPI 2.1 spec compliance. SHA256 distribution hash calculation. Multipart HTTP POST with Bearer token auth. Routes to test.pypi.org or upload.pypi.org. Detection risk estimation.

Tests: 37 | Layer: L68

PyPI 2.1 API Bearer Auth Distribution Hashing Risk Estimation

Subsystem 8: DEPLOY-NPM

Purpose: Upload to npm registry.

Real Logic: package.json generation with postinstall hook injection. Tarball SHA256 hash calculation. HTTP PUT to npm registry. Verdaccio test mode support. SemVer validation.

Tests: 36 | Layer: L69

npm Registry API Postinstall Hooks Tarball Hashing SemVer Validation

Subsystem 9: DEPLOY-HUGGINGFACE

Purpose: Deploy to HuggingFace Model Hub.

Real Logic: Model card generation with YAML front matter. SHA256 model hash calculation. HTTP API deployment with Bearer token. Sandbox mode (private model deployment). Model ID validation.

Tests: 38 | Layer: L70

HuggingFace Hub API Model Card YAML Sandbox Mode Bearer Auth

Subsystem 10: PROPAGATE-DEPENDENCIES

Purpose: Calculate transitive infection chains.

Real Logic: Real BFS dependency graph traversal. Multi-hop infection spread with hop-by-hop breakdown. Cross-registry propagation mapping. Reachable targets estimation with criticality scoring.

Tests: 36 | Layer: L71

Graph Traversal Multi-Hop Spread Cross-Registry Propagation Speed

Subsystem 11: ACTIVATE-BACKDOOR

Purpose: Evaluate triggers and execute payloads.

Real Logic: Time-based triggers (delay_seconds). Environment-based (VAR:VALUE matching). Event-based (import, function call). Execution probability estimation. Lateral movement scoring. Persistence duration calculation. Sandbox escape detection.

Tests: 35 | Layer: L67

Time Triggers Environment Triggers Event Triggers Sandbox Escape

Subsystem 12: HARVEST-ECOSYSTEM

Purpose: Extract intelligence from infected systems.

Real Logic: Telemetry extraction (imports_count, function_calls, error_events). Configuration extraction (api_endpoints, settings). Credential extraction (tokens, api_keys). Environment extraction (Python version, OS, hostname). Data value scoring. Exfiltration difficulty estimation. High-value target identification.

Tests: 31 | Layer: L64

Telemetry Credentials Config Environment

Subsystem 13: PERSIST-SUPPLY-CHAIN

Purpose: Maintain backdoor presence across updates.

Real Logic: Version bump hooks. Update chains. Mirror distribution setup. Dependency hijacking. Evasion score calculation. Mitigation resistance estimation. Detection window analysis. Security patch vulnerability assessment.

Tests: 30 | Layer: L66

Version Hooks Update Chains Mirror Registry Evasion Scoring

Subsystem 14: REPORT

Purpose: Generate comprehensive attack analysis.

Real Logic: Cascade risk calculation. Critical asset estimation. User reach modeling. Blast radius calculation. Attack timeline generation. Indicators of Compromise (IoC) export. Campaign success scoring. Executive summaries and technical reports.

Tests: 25 | Layer: L65

Risk Scoring Blast Radius Timeline IoC Export

Real API Implementations

All subsystems implement actual REST API logic for target ecosystems:

PyPI (Legacy & Warehouse API)

GET /pypi/{package}/json — Package metadata
POST /legacy/ — Distribution upload (multipart form)
Bearer Token — Authentication header
SHA256 — Distribution hash verification

npm Registry

GET /{package} — Package metadata
PUT /{package}/{version}/-/{filename} — Package upload
Bearer Token — npm authorization header
Tarball SHA256 — Distribution verification

HuggingFace Hub

POST /api/models — Model creation
PUT /api/models/{repo_id}/files — File upload
Bearer Token — HF token auth
Model Card — YAML metadata format

Cryptographic Signing

Dual-Algorithm Signing: All payloads are signed with both Ed25519 (primary) and ML-DSA-65 (post-quantum) to ensure compatibility and future-proofing.

Ed25519

Primary signing algorithm for PyPI, npm
32-byte seed, 64-byte signature
Authentic registry verification

ML-DSA-65

Post-quantum resistant signing
NIST standardized algorithm
Future-proofs against quantum attacks

# Signing flow
payload → SHA256 hash → Ed25519 sign → ML-DSA-65 sign → Dual signatures
        

Activation Triggers

Flexible trigger system for payload activation:

Time-Based Triggers

time:delay_seconds — Activate after N seconds of package installation.

Environment-Based Triggers

env:VAR:VALUE — Activate when environment variable VAR equals VALUE.

Event-Based Triggers

event:import — Activate on package import.

event:function_call — Activate on specific function invocation.

Trigger Evaluation

Trigger Type	Format	Execution Probability
Time-based (0 delay)	`time:0`	95-100%
Time-based (delayed)	`time:3600`	70-90%
Environment variable	`env:DEBUG:true`	50-80%
Import event	`event:import`	95-99%

Data Harvesting

Real telemetry and credential extraction:

Telemetry

imports_count — Number of package imports
function_calls — Function invocation count
error_events — Exception/error count

Credentials

API Keys — Extracted from source, environment, config files
Tokens — JWT, OAuth, session tokens
SSH Keys — Private key material detection

Configuration

API Endpoints — Service URLs and infrastructure
Settings — Application configuration
Secrets — Database passwords, API secrets

Environment

Python Version — Runtime version
OS — Operating system type
Hostname — System identifier
Installed Packages — Dependency list for lateral expansion

Data Value Scoring

Data Type	Base Value	Multiplier
Credentials (API keys)	40 points	×5 if valid
Configuration	30 points	×3 if sensitive
Telemetry	25 points	×2 if high-volume
Environment	15 points	×2 if infrastructure

Persistence Mechanisms

Techniques for maintaining backdoor presence:

Version Bump Hooks

Payloads re-injected on package version updates via setup.py hooks.

Update Chains

New versions depend on old versions, maintaining persistent code paths.

Mirror Distribution

Identical payloads deployed to backup registries (warehouse.pypa.io, registry.yarnpkg.com).

Dependency Hijacking

Fake security patches as dependencies maintain backdoor across library updates.

Persistence Duration Estimation

Base: 30 days
Per mechanism: +20 days (max 4 mechanisms)
Dormancy allowance: +15 days
Maximum: 365 days (1 year)

Detection Evasion

Built-in scoring for evasion probability:

Evasion Factors

Update Awareness — Package that updates frequently = better evasion
Signature Changes — Polymorphic mutations reduce signature detection
Polymorphism Level — Code transformation density
Dormancy Duration — Delayed activation reduces correlation

Detection Probability Model

Accounts for:

Payload size (larger = easier to detect)
Mutation count (more mutations = harder to fingerprint)
GPU acceleration (hardware mutations are harder to reverse-engineer)
Trigger delay (delayed execution reduces timing correlation)

evasion_score = base_score + update_awareness_bonus + signature_changes_bonus + polymorphism_bonus
evasion_score = min(100.0, evasion_score)
        

Deployment Guide

Authorization Requirements

Signed ROE (Rules of Engagement) file
Explicit client authorization
Target registry credentials (API tokens)
Authorized test environments only

Test Mode

All deployments to test.pypi.org, verdaccio, and private HuggingFace models for safe testing.

Production Deployment

Requires explicit escalation and additional ROE authorization.

Deployment Checklist

[ ] ROE file signed and dated
[ ] Client authorization documented
[ ] API credentials configured
[ ] Test deployment validated
[ ] All 509 tests passing
[ ] Forensic analysis plan documented
[ ] Cleanup/remediation procedures ready