Metadata-Version: 2.4
Name: picoshogun
Version: 1.0.0
Summary: Command centre for the Pico Security Series — security orchestration, firewall, and monitoring
Author-email: Henrik Kirk <kirk@kirkforge.dev>
Maintainer-email: KirkForge <kirk@kirkforge.dev>
License-Expression: BUSL-1.1
Project-URL: Homepage, https://github.com/KirkForge/PicoShogun
Project-URL: Documentation, https://github.com/KirkForge/PicoShogun#readme
Project-URL: Repository, https://github.com/KirkForge/PicoShogun
Project-URL: Issues, https://github.com/KirkForge/PicoShogun/issues
Project-URL: Changelog, https://github.com/KirkForge/PicoShogun/blob/main/CHANGELOG.md
Project-URL: Release Notes, https://github.com/KirkForge/PicoShogun/releases
Project-URL: Source Code, https://github.com/KirkForge/PicoShogun
Project-URL: Bug Tracker, https://github.com/KirkForge/PicoShogun/issues
Keywords: security,orchestration,command-centre,fastapi,firewall,supply-chain,anomaly-detection,monitoring
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Framework :: FastAPI
Classifier: Topic :: Security
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Environment :: Console
Classifier: Framework :: Pytest
Classifier: Typing :: Typed
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE-SUMMARY.md
License-File: COMMERCIAL-LICENSE.md
Requires-Dist: fastapi>=0.104.0
Requires-Dist: uvicorn[standard]>=0.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: PyJWT>=2.8.0
Requires-Dist: python-jose[cryptography]>=3.3.0
Requires-Dist: passlib[bcrypt]>=1.7.4
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: requests>=2.31.0
Requires-Dist: starlette>=0.27.0
Requires-Dist: croniter>=1.0.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: observability
Requires-Dist: opentelemetry-api>=1.20.0; extra == "observability"
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "observability"
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20.0; extra == "observability"
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.41b0; extra == "observability"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: httpx>=0.24.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: bandit>=1.7.0; extra == "dev"
Requires-Dist: pip-audit>=0.7.0; extra == "dev"
Dynamic: license-file

![PicoShogun Banner](docs/banner.png)

# PicoShogun — Command Centre for the Pico Security Series

[![CI](https://github.com/KirkForge/PicoShogun/actions/workflows/ci.yml/badge.svg)](https://github.com/KirkForge/PicoShogun/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/picoshogun)](https://pypi.org/project/picoshogun/)
[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)
[![Tests](https://img.shields.io/badge/tests-170%20passing-brightgreen)](https://github.com/KirkForge/PicoShogun)
[![License: BUSL-1.1](https://img.shields.io/badge/license-BUSL--1.1-blue)](LICENSE)
[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support%20my%20hardware-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/kirkforge)

Command centre, firewall, and monitoring for the Pico Security Series. FastAPI + SQLite + Python 3.12.

| Product | Purpose | Repo |
|---------|---------|------|
| PicoSentry | L2 Supply-chain scanner | KirkForge/PicoSentry |
| PicoDome | L3/L4 Runtime sandbox | KirkForge/PicoDome |
| **PicoShogun** | **Command centre & firewall** | **KirkForge/PicoShogun** |
| PicoWatch | L5-L7 LLM defense | KirkForge/PicoWatch |

## Status

**Pre-1.0 beta.** Active development started late May 2026. The core API, auth, middleware stack, and orchestration work. The frontend dashboard is functional but rough. Several features are honest limitations — see STATE.md and GAPS.md for what's real vs. aspirational.

## Quick Start

```bash
# Setup
bash scripts/setup.sh
source .venv/bin/activate

# Start API
python -m uvicorn api.server:app --reload

# Or use the entrypoint
picoshogun
# (shogun also works as backward compat alias)
```

## Environment Variables

Primary prefix is `PICOSHOGUN_*`. `SHOGUN_*` works as backward compat.

| Variable | Default | Description |
|----------|---------|-------------|
| `PICOSHOGUN_ENV` | `development` | Environment (`development`/`production`) |
| `PICOSHOGUN_SECRET_KEY` | **required in production** | JWT signing key — `assert_secure()` refuses boot with default |
| `PICOSHOGUN_CORS_ORIGINS` | `http://localhost:8765` | Comma-separated CORS origins |
| `PICOSHOGUN_DDOS_SHIELD` | `false` | Enable DDoS shield |
| `PICOSHOGUN_DB_PATH` | `picoshogun.db` | SQLite database path |
| `PICOSHOGUN_API_PORT` | `8765` | API listen port |
| `PICOSHOGUN_AUDIT_RETENTION_DAYS` | `90` | Audit log retention period |

See `.env.example` for the full list.

## Features

- **12-layer middleware stack**: SecurityHeaders → RequestID → RequestSizeLimit → DDoSShield → GZip → CORS → CORSHardening → RateLimit → Audit → Timeout → HTTPS → DocsRestriction
- **Rate limiting**: Per-IP (100/min) + per-org (1000/min) with SQLite persistence
- **JWT + API keys + RBAC**: 18 permissions across viewer/operator/admin roles, API key rotation, expired key cleanup
- **Audit log management**: Per-severity retention, purge API, dry-run support
- **Graceful shutdown**: SIGTERM/SIGINT handlers for Kubernetes pod termination
- **Pico Series Orchestration**: Run PicoSentry, PicoDome, and PicoWatch via the orchestrator
- **Intelligence Engine**: 16-pattern threat extraction with FP filtering and correlation
- **Alert Hub**: Multi-channel alerts (Discord webhook, Slack/Email/Syslog)
- **Metrics**: Prometheus-compatible with built-in collection
- **Scheduler**: Cron-based job scheduling
- **Backup/Restore**: Compressed archives with retention
- **Event Bus**: Pub/sub with WebSocket real-time streaming
- **Plugin system**: Dynamic loading with Ed25519 signed manifest verification

## Security

### Startup Validation
PicoShogun refuses to boot in production with insecure defaults. The `assert_secure()` check runs on startup and enforces:
- **No default secret key** — `PICOSHOGUN_SECRET_KEY` must be set; the default is rejected in production
- **No wildcard CORS** — `PICOSHOGUN_CORS_ORIGINS` must list explicit origins in production
- **No wildcard allowed hosts** — `PICOSHOGUN_ALLOWED_HOSTS` must be explicit in production
- **No debug mode** — `PICOSHOGUN_DEBUG=false` in production

Override with `PICOSHOGUN_SKIP_SECURE_ASSERT=1` (not recommended; only for CI/testing).

### TLS Termination
PicoShogun does not terminate TLS itself. It expects to run behind a reverse proxy (nginx, Caddy, cloud load balancer) that handles TLS.

### Plugin Trust Boundary
The plugin system loads Python modules from the `plugins/` directory at runtime. **This directory is a trust boundary equivalent to giving someone a shell on the server.** Plugin code runs in-process with full access to the runtime, database, and network.

### Token Auth
JWT (PyJWT) for authentication. The legacy simple-token format has been removed — it used non-timing-safe comparison and lacked expiration claims.

## Architecture

```
api/server.py              # FastAPI REST API + WebSocket + Dashboard (248 lines)
api/routers/                # 12 router modules
config/settings.py         # Dataclass config from env vars (PICOSHOGUN_*)
config/project_registry.json  # Pico series project definitions
database/manager.py        # Thread-safe SQLite WAL + migrations + ConnectionPool interface
services/auth.py           # JWT + API keys + RBAC + expiration enforcement
services/orchestrator.py   # Pico series tool runner with concurrency control
services/intelligence.py   # 16-pattern threat engine with FP filtering
services/alert_hub.py      # Multi-channel alerts
services/rbac.py           # 18 permissions, 3 roles
middleware/                # 12-layer middleware stack
plugins/                  # Dynamic plugin loading + signed manifests
```

See `STATE.md` for the full architecture diagram.

## API Endpoints

Base URL: `http://localhost:8765`

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/health` | — | Full health check (readiness) |
| GET | `/health/live` | — | Liveness probe |
| GET | `/health/ready` | — | Readiness probe (DB connected) |
| GET | `/status` | Bearer | System status |
| GET | `/projects` | Bearer+Org | List projects |
| POST | `/projects/{id}/run` | Bearer+Org | Trigger project run |
| GET | `/intelligence` | Bearer | Intelligence signals |
| GET | `/audit/stats` | Bearer | Audit statistics + retention |
| POST | `/audit/purge` | Admin | Purge audit logs |
| POST | `/auth/api-key/{id}/rotate` | Bearer | Rotate API key |
| DELETE | `/auth/api-key/{id}` | Bearer | Revoke API key |
| GET | `/api/v1/scans` | Bearer | Supply chain scans |
| POST | `/api/v1/sandboxes` | Bearer+Operator | Sandbox execution |
| WS | `/ws` | Optional | Real-time event stream |

Full endpoint list in `STATE.md`.

## Testing

```bash
python -m pytest tests/ -v                    # Main tests (170+)
ruff check .                                    # Lint
```

## Docker

```bash
docker build -t picoshogun:latest .
docker run -d -p 8765:8765 \
  -e PICOSHOGUN_SECRET_KEY=your-production-secret \
  -e PICOSHOGUN_ENV=production \
  -e PICOSHOGUN_CORS_ORIGINS=https://app.example.com \
  picoshogun:latest
```

## License

BUSL-1.1
