pulsar_sentinel
Try Claude free for 2 weeks — the AI powering this ecosystem. Start your free trial →
PULSAR SENTINEL
Try Claude free for 2 weeks — the AI behind this entire ecosystem. Start your free trial →
Post-Quantum Cryptography Security Framework — LIVE on Port 8250
A production-grade blockchain-integrated security layer providing quantum-resistant encryption (ML-KEM-768/1024), immutable audit trails (Agent State Records with Merkle proofs), real-time threat scoring (PTS), and role-based access control. Protecting the ShaneBrain 4-node cluster and the 800M Windows users facing security update deprecation.
Currently protecting: ShaneBrain ecosystem — 42 MCP tools, 4-node Ollama cluster, Mega Dashboard, Angel Cloud Gateway, Weaviate vector DB.
This project operates under the ShaneTheBrain Constitution.
Live Status
| Endpoint | Status |
|---|---|
| Health | curl http://localhost:8250/api/v1/health |
| Swagger Docs | http://100.67.120.6:8250/docs |
| Dashboard | http://100.67.120.6:8250/dashboard |
Infrastructure
Runs on the ShaneBrain 4-node cluster — Pi 5 controller + 3 headless Windows worker nodes.
| Component | Details |
|---|---|
| Compute | Raspberry Pi 5, 16GB RAM |
| Chassis | Pironman 5-MAX by Sunfounder |
| Storage | RAID 1 — 2x WD Blue SN5000 2TB NVMe (mdadm) |
| Core Path | /mnt/shanebrain-raid/shanebrain-core/ |
| Backup | 8TB Seagate USB — restic encrypted, daily |
| Network | Tailscale VPN across all devices |
| OS | Raspberry Pi OS (Debian Trixie, arm64) |
Overview
PULSAR SENTINEL implements a three-tier security architecture:
| Tier | Name | Features | Price |
|---|---|---|---|
| 1 | Sentinel Core | ML-KEM PQC, 10M ops/month, Daily ASR | $16.99/mo |
| 2 | Legacy Builder | AES-256, 5M ops/month, Weekly ASR | $10.99/mo |
| 3 | Autonomous Guild | Full PQC + Smart Contracts, Unlimited | $29.99/mo |
Security Features
Post-Quantum Cryptography
- ML-KEM-768/1024: NIST-approved lattice-based key encapsulation
- Hybrid Encryption: ML-KEM + AES-256-GCM for defense in depth
- Key Rotation: Automatic 90-day key rotation (configurable)
Classical Cryptography (Legacy)
- AES-256-CBC: HMAC-SHA256 authenticated encryption
- ECDSA secp256k1: Polygon-compatible signatures
- TLS 1.3: Enforced transport security
Blockchain Integration
- Polygon Network: Mainnet and Amoy testnet support
- MetaMask Auth: Wallet-based passwordless authentication
- Immutable Logging: ASR records with Merkle proofs
Quick Start
Installation
# Clone the repository
git clone https://github.com/thebardchat/pulsar_sentinel.git
cd pulsar_sentinel
# Create virtual environment
python -m venv venv
source venv/bin/activate # Linux/Mac
# or: venv\Scripts\activate # Windows
# Install dependencies
pip install -r requirements.txt
# Copy environment template
cp .env.template .env
# Edit .env with your configuration
Running the Server
# Development mode
python -m uvicorn api.server:app --reload --host 0.0.0.0 --port 8000
# Production mode
python -m api.server
API Documentation
Once running, access the API docs at:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
API Endpoints
Authentication
# Request nonce
POST /api/v1/auth/nonce
{"wallet_address": "0x..."}
# Verify signature
POST /api/v1/auth/verify
{"wallet_address": "0x...", "signature": "0x...", "nonce": "..."}
Cryptography
# Generate keys
POST /api/v1/keys/generate?algorithm=hybrid
# Encrypt data
POST /api/v1/encrypt
{"data": "base64...", "algorithm": "hybrid", "public_key": "base64..."}
# Decrypt data
POST /api/v1/decrypt
{"ciphertext": "base64...", "algorithm": "hybrid", "secret_key": "base64..."}
Status & Monitoring
# Health check (no auth)
GET /api/v1/health
# System status
GET /api/v1/status
# Get PTS score
GET /api/v1/pts/{user_id}
# Get ASR records
GET /api/v1/asr/{user_id}
Discord Community
Join the PULSAR SENTINEL Discord for real-time threat alerts and community support.
Bot Commands:
| Command | Description |
|———|————-|
| !help | Show all commands |
| !status | System health check |
| !pricing | View subscription tiers |
| !pts | PTS formula & thresholds |
| !docs | Documentation links |
| !invite | Get Discord invite link |
Automated Features:
- Push notifications on every commit to
main(via GitHub Actions webhook) - Welcome messages for new members
- Real-time PTS threat tier change alerts
# Run the Discord bot
python scripts/run_discord_bot.py
Architecture
pulsar_sentinel/
├── src/
│ ├── core/ # Cryptographic engines
│ │ ├── pqc.py # ML-KEM + hybrid encryption
│ │ ├── legacy.py # AES-256, ECDSA, TLS
│ │ └── asr_engine.py # Agent State Records
│ ├── blockchain/ # Polygon integration
│ │ ├── polygon_client.py
│ │ ├── smart_contract.py
│ │ └── event_logger.py
│ ├── governance/ # Self-governance
│ │ ├── rules_engine.py # RC codes
│ │ ├── pts_calculator.py # Threat scoring
│ │ └── access_control.py # RBAC
│ ├── discord_bot/ # Discord community bot
│ │ ├── bot.py # Main bot + events
│ │ ├── commands.py # !help, !status, !pricing, etc.
│ │ ├── embeds.py # Themed embed builders
│ │ └── alerts.py # PTS threat alert system
│ └── api/ # REST API
│ ├── server.py
│ ├── auth.py
│ └── routes.py
├── tests/ # Comprehensive test suite
├── config/ # Configuration
├── scripts/ # Deployment scripts
└── docs/ # Documentation
Governance Rules (RC Codes)
| Code | Rule | Description |
|---|---|---|
| RC 1.01 | Signature Required | All requests require encryption signature |
| RC 1.02 | Heir Transfer | 90-day unresponsive triggers heir transfer |
| RC 2.01 | Three-Strike Rule | 3 violations = temporary ban |
| RC 3.02 | Transaction Fallback | Auto-fallback to Gryphon on TX failure |
Points Toward Threat Score (PTS)
PTS = (quantum_risk * 0.4) + (access_violations * 0.3) +
(rate_limit_hits * 0.2) + (signature_failures * 0.1)
Tier 1 (Safe): PTS < 50 [Green]
Tier 2 (Caution): PTS 50-149 [Yellow]
Tier 3 (Critical): PTS >= 150 [Red]
Testing
# Run all tests
pytest
# Run with coverage
pytest --cov=src --cov-report=html
# Run specific test categories
pytest -m pqc # PQC tests
pytest -m blockchain # Blockchain tests
pytest -m governance # Governance tests
Configuration
Key environment variables (see .env.template):
| Variable | Description | Default |
|---|---|---|
POLYGON_NETWORK |
mainnet or testnet | testnet |
PQC_SECURITY_LEVEL |
768 or 1024 | 768 |
KEY_ROTATION_DAYS |
Key rotation interval | 90 |
RATE_LIMIT_DEFAULT |
Requests per minute | 5 |
STRIKE_THRESHOLD |
Strikes before ban | 3 |
DISCORD_BOT_TOKEN |
Discord bot token | |
DISCORD_WEBHOOK_URL |
Discord webhook URL |
Requirements
- Python 3.11+
- liboqs-python (for PQC operations)
- Web3.py (for blockchain)
- FastAPI (for REST API)
Part of the Angel Cloud Ecosystem
| Project | Repo | Status |
|---|---|---|
| Constitution | thebardchat/constitution | Active |
| ShaneBrain Core | thebardchat/shanebrain-core | Active |
| Pulsar Sentinel | thebardchat/pulsar_sentinel | Active |
| Loudon/DeSarro | thebardchat/loudon-desarro | Active |
Credits
| Partner | Contribution |
|---|---|
| Claude by Anthropic | Co-built ecosystem infrastructure |
| Raspberry Pi 5 | Affordable local compute |
| Pironman 5-MAX by Sunfounder | RAID-capable NVMe chassis |
License
MIT License - See LICENSE for details.
Built with Claude (Anthropic) · Runs on Raspberry Pi 5 + Pironman 5-MAX
“Build it once. Secure it forever.”
Support This Work
If what I’m building matters to you — local AI for real people, tools for the left-behind — here’s how to help:
- Sponsor me on GitHub
- Buy the book — You Probably Think This Book Is About You
- Star the repos — visibility matters for projects like this
Built by Shane Brazelton · Co-built with Claude (Anthropic) · Hazel Green, Alabama