Metadata-Version: 2.4
Name: qriton-shield
Version: 3.2.1
Summary: Real-time IP threat intelligence. Detect and block malicious IPs with a global network of Shields. REST API for any stack.
Project-URL: Homepage, https://shield.qriton.com
Project-URL: Repository, https://github.com/qriton/shield
Project-URL: Issues, https://github.com/qriton/shield/issues
Project-URL: Documentation, https://shield.qriton.com/docs/python
Author-email: Qriton <shield@qriton.com>
License-Expression: Apache-2.0
Keywords: anomaly-detection,attack-prevention,bot-detection,ddos,firewall,hopfield-network,ip-blocking,rate-limiting,real-time-protection,security,threat-intelligence,waf
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Topic :: Security
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Networking :: Firewalls
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Qriton Shield

Real-time IP threat intelligence with Modern Hopfield Networks. Detect and block malicious IPs with AI-powered anomaly detection, a 4-tier response system, and a global network of Shields.

## Installation

```bash
pip install qriton-shield
```

## Quick Start

```python
from datetime import datetime
from qriton_shield import Shield, HttpRequest

shield = Shield()
shield.start()

# Process an HTTP request
result = shield.process_request(HttpRequest(
    timestamp=datetime.now(),
    client_ip="192.168.1.100",
    method="GET",
    url="/api/data",
    status_code=200,
    bytes_sent=1024,
    bytes_received=256,
    user_agent="Mozilla/5.0",
))

print(f"Decision: {result.decision}")  # allow | rate_limit | challenge | block
print(f"Tier: {result.tier}")          # 0-3
print(f"Threat Score: {result.threat_score}")
print(f"Anomaly Score: {result.anomaly_score}")

shield.stop()
```

## Features

- **Modern Hopfield Networks** — Continuous Hopfield Network with LogSumExp energy function for exponential-capacity anomaly detection
- **20-Feature Analysis** — Network (L4), application (L7), and malware (V2) traffic features with gradient-based attribution
- **4-Tier Response** — Allow (0-30) -> Rate Limit (30-60) -> Challenge (60-80) -> Block (80+)
- **Adaptive Threat Modes** — relaxed / balanced / aggressive / lockdown with auto-escalation
- **Web Application Firewall** — OWASP Top 10 pattern detection (SQLi, XSS, path traversal, command injection)
- **Cross-Platform Firewall** — Windows routes, Linux iptables, macOS pfctl
- **Subnet Velocity Detection** — Auto-aggregate /24 blocks for coordinated attacks
- **Challenge/Trust System** — Behavioral verification with trust tokens
- **Night Mode** — Automatic minimum protection during off-hours
- **Geographic Fencing** — Country-based blocking with risk multipliers
- **Threat Intelligence** — Spamhaus, Firehol, AbuseIPDB integration
- **CDN Whitelist** — Cloudflare, AWS CloudFront, Google, Fastly auto-whitelisted
- **Federated Learning** — Cross-shield Hopfield model sharing
- **Data Exfiltration Detection** — Credit cards, SSNs, API keys, private keys
- **Troll Mode** — Rickrolls, tarpits, honeypots, fake vulnerabilities
- **MCP Guard** — Firewall for Claude MCP tool calls (prompt injection detection)
- **Hash-Chain Audit Log** — Tamper-evident decision trail for compliance
- **7-Layer Pipeline (v2)** — Network, Transport, Identity, Capability, Semantic, State, Collective

## CLI

```bash
# Start Shield server
shield -m balanced -p 8765

# Start with config file
shield -c settings.json

# Monitor a log file
shield -l /var/log/nginx/access.log

# Security audit
shield audit

# Version
shield version
```

## API

```python
from qriton_shield import Shield, ShieldConfig, NightModeConfig

# Full configuration
config = ShieldConfig(
    threat_mode="balanced",
    state_path="shield_state.json",
    night_mode=NightModeConfig(enabled=True, start_hour=22, end_hour=6, minimum_mode="balanced"),
)

shield = Shield(config)
shield.on("block", lambda d: print(f"Blocked {d['ip']}: {d['reason']}"))
shield.on("anomaly", lambda d: print(f"Anomaly score: {d['score']:.1f}"))
shield.start()
```

### Hopfield Network (standalone)

```python
from qriton_shield import ContinuousHopfieldNetwork

net = ContinuousHopfieldNetwork(20, beta=1.0)
net.train([pattern1, pattern2, pattern3])
result = net.recall(noisy_input)
print(f"Energy: {result.final_energy}, Converged: {result.converged}")
```

### WAF

```python
from qriton_shield import WafEngine

waf = WafEngine()
match = waf.check("/search?q=1' UNION SELECT * FROM users--")
if match:
    print(f"WAF: {match.category} ({match.rule_name}), score={match.score}")
```

### MCP Guard

```python
from qriton_shield import MCPGuard

guard = MCPGuard()
result = guard.check_tool_call("filesystem_write", {"path": "/etc/passwd", "content": "..."})
if not result["allowed"]:
    print(f"Blocked: {result['reason']}")
```

### Geographic Fencing

```python
from qriton_shield import GeoFencing, GeoConfig

geo = GeoFencing(GeoConfig(
    enabled=True,
    whitelist=["US", "DE", "GB"],
    high_risk_countries=["CN", "RU", "KP"],
))
info = geo.check_ip("8.8.8.8")
print(f"Country: {info['country']}, High Risk: {info['is_high_risk']}")
```

## Threat Modes

| Mode | Anomaly Threshold | SYN Timeout | HTTP RPM Limit |
|------|-------------------|-------------|----------------|
| relaxed | 0.8 | 60s | 500 |
| balanced | 0.6 | 45s | 300 |
| aggressive | 0.4 | 10s | 100 |
| lockdown | 0.2 | 5s | 30 |

## Architecture

```
HTTP Request
    |
    v
[Whitelist Check] --> bypass if CDN/known-good
    |
[Threat Scoring] --> L4 + L7 + credential stuffing + rate acceleration
    |
[Hopfield AI] --> 20-feature anomaly detection with explainability
    |
[4-Tier Response]
    |-- Tier 0: Allow (score < 30)
    |-- Tier 1: Rate Limit (30-60)
    |-- Tier 2: Challenge (60-80)
    |-- Tier 3: Block (80+)
    |
[Auto Mode Switch] --> escalate/deescalate based on block rate
```

## Requirements

- Python >= 3.10
- No external dependencies (pure Python)

## Links

- **Homepage**: https://shield.qriton.com
- **NPM Package**: https://www.npmjs.com/package/@qriton/shield
- **Repository**: https://github.com/qriton/shield

## License

Apache-2.0
