shieldlayer 0.2.0

Enterprise API Security Middleware for FastAPI and Flask

🛡 ShieldLayer

Enterprise API Security Middleware for FastAPI and Flask

ShieldLayer provides plug-and-play enterprise-grade security for your Python APIs — covering rate limiting, abuse detection, API key management, geo-blocking, and threat scoring — all in one package.

---

🚀 Quick Start

Install

pip install shieldlayer

# With FastAPI support
pip install shieldlayer[fastapi]

# With Flask support
pip install shieldlayer[flask]

# Everything
pip install shieldlayer[all]

FastAPI — 3 lines of protection

from shieldlayer import SecureAPI

secure = SecureAPI()
app.middleware("http")(secure.fastapi_middleware)

Flask — 2 lines of protection

from shieldlayer import SecureAPI

secure = SecureAPI()
secure.init_flask(app)

---

✨ Features

Feature	Free	Pro
Redis Rate Limiting (per IP, key, endpoint)	✅	✅
API Key Management (generate, rotate, revoke)	✅	✅
Brute Force Detection	✅	✅
Rapid Endpoint Switching Detection	✅	✅
Security Audit CLI	✅	✅
Threat Scoring Engine	❌	✅
Geo Blocking	❌	✅
Behavior Pattern Detection	❌	✅
Webhook Alerts	❌	✅

---

🛡 Core Components

1. Rate Limiting

Uses a sliding window algorithm backed by Redis (with in-memory fallback for development).

from shieldlayer import SecureAPI
from shieldlayer.config import ShieldLayerConfig, RateLimitConfig

config = ShieldLayerConfig(
    rate_limit=RateLimitConfig(
        requests_per_minute=60,
        requests_per_hour=1000,
        per_ip=True,
        per_api_key=True,
        per_endpoint=False,
    )
)
secure = SecureAPI(config=config)

Response headers automatically added:

X-RateLimit-Remaining: 42
Retry-After: 30        ← only when blocked

---

2. API Key Management

Full lifecycle: generate → validate → rotate → revoke.

from shieldlayer.api_keys.manager import APIKeyManager
from shieldlayer.config import APIKeyConfig

mgr = APIKeyManager(APIKeyConfig())

# Create
key = mgr.create(user_id="user_123", name="Production Key")
print(key["plain_key"])   # sl_Xk7j... — store this once!

# Validate (in your auth middleware)
record = mgr.validate(request.headers["X-Api-Key"])

# Rotate
new_key = mgr.rotate(key["key_id"])

# Revoke
mgr.revoke(key["key_id"])

---

3. Abuse Detection

Catches: failed login floods, rapid endpoint scanning, and extreme request frequency.

# Record a failed login attempt
secure._abuse_detector.record_failed_login(f"ip:{client_ip}", "/login")

# Record a request (called automatically by middleware)
secure._abuse_detector.record_request(f"ip:{client_ip}", request.path)

When threshold is hit → AbuseDetected exception → 403 Forbidden response.

---

4. Threat Scoring Engine (Pro)

Composite scoring from multiple risk signals:

from shieldlayer.core.scoring import ThreatScorer
from shieldlayer.config import ThreatScoringConfig

scorer = ThreatScorer(ThreatScoringConfig(
    block_threshold=7.5,
    alert_webhook_url="https://your-webhook.com/alerts",
))

report = scorer.assess(
    identifier="ip:1.2.3.4",
    failed_attempts=8,
    geo_mismatch=True,
    ip_reputation_score=6.5,
    unusual_patterns=3,
)

print(report.total_score)       # 0–10
print(report.recommendation)   # allow | monitor | temp_block | perm_block

---

5. Geo Blocking (Pro)

from shieldlayer.config import GeoBlockConfig, ShieldLayerConfig

config = ShieldLayerConfig(
    geo_block=GeoBlockConfig(
        enabled=True,
        blocked_countries=["CN", "RU", "KP"],   # blocklist mode
        # OR
        allowed_countries=["US", "GB", "IN"],   # allowlist mode (stricter)
        geoip_db_path="/path/to/GeoLite2-Country.mmdb",  # optional
    )
)

---

🖥 CLI

# Initialize config file
shieldlayer init

# Run full security audit
shieldlayer audit

# Check component status
shieldlayer status

# Manage API keys
shieldlayer key create user_123 --name "Production"
shieldlayer key list user_123
shieldlayer key rotate <key_id>
shieldlayer key revoke <key_id>

Example audit output:

Check                                    Status     Points
─────────────────────────────────────────────────────────────
Redis connectivity                       ✅ PASS    +2.0
Database connectivity                    ✅ PASS    +1.0
Abuse detection (config)                 ✅ PASS    +2.0
Threat scoring (Pro)                     ❌ FAIL     2.0

🛡  Security Score: 7.4/10.0

---

📦 Package Structure

shieldlayer/
├── core/
│   ├── middleware.py      ← SecureAPI (main entry point)
│   ├── rate_limit.py      ← Sliding window rate limiter
│   ├── abuse.py           ← Abuse & brute-force detection
│   └── scoring.py         ← Threat scoring engine (Pro)
├── api_keys/
│   ├── manager.py         ← API key full lifecycle
│   └── rotation.py        ← Background rotation scheduler
├── geo/
│   └── geo_block.py       ← Country-based blocking (Pro)
├── cli/
│   └── main.py            ← CLI commands
├── config.py              ← All configuration dataclasses
├── exceptions.py          ← Custom exceptions
└── utils.py               ← Helpers

---

🔒 Security Response Headers

ShieldLayer automatically injects secure response headers:

Header	Description
X-RateLimit-Remaining	Requests remaining in current window
X-ShieldLayer-Latency	ShieldLayer middleware overhead (ms)
Retry-After	Seconds to wait after rate limit hit

---

⚙ Full Configuration Reference

from shieldlayer.config import ShieldLayerConfig

config = ShieldLayerConfig(
    redis_url="redis://localhost:6379/0",
    redis_prefix="myapp",

    # IP whitelisting / blacklisting
    whitelist_ips=["10.0.0.1"],
    blacklist_ips=["1.2.3.4"],

    rate_limit=RateLimitConfig(
        requests_per_minute=60,
        requests_per_hour=1000,
        burst_size=10,
        per_ip=True,
        per_api_key=True,
        per_endpoint=False,
    ),
    abuse_detection=AbuseDetectionConfig(
        enabled=True,
        max_failed_logins=5,
        failed_login_window=300,
        rapid_switch_threshold=20,
        suspicious_frequency_threshold=100,
        block_duration=3600,
    ),
    # Pro features:
    threat_scoring=ThreatScoringConfig(
        enabled=True,
        block_threshold=7.5,
        alert_threshold=5.0,
        perm_block_threshold=9.5,
        alert_webhook_url="https://hooks.slack.com/...",
    ),
    geo_block=GeoBlockConfig(
        enabled=True,
        blocked_countries=["CN", "RU"],
        geoip_db_path="/path/to/GeoLite2-Country.mmdb",
    ),
)

---

🧪 Running Tests

pip install shieldlayer[dev]
pytest tests/ -v

---

📄 License

MIT License. See LICENSE.

---

💼 Commercial Licensing

For Pro features (Threat Scoring, Geo Blocking, Behavior Detection, Webhook Alerts), contact us at: [e-mail]

Pricing:

• Pro: $79/month — Threat scoring, geo-blocking, webhooks
• Enterprise: $299/month — SLA, custom rules, dedicated support