tornadoapi-guard 2.0.0

Documentation

📚 Documentation - full technical documentation for this package.

🛡️ Guard Core - the engine's reference documentation.

🤖 Monitoring Agent Integration - monitor your Guard instance with a monitoring agent.

tornadoapi-guard is a security library for Tornado that provides middleware to control IPs, log requests, detect penetration attempts and more. It integrates seamlessly with Tornado to offer robust protection against various security threats. Powered by guard-core.

Website · Docs · Playground · Dashboard · Discord

Ecosystem

Guard Core is the Python engine. Framework adapters are thin wrappers that translate native request/response types into Guard Core's protocols. The telemetry agents ship security events and metrics to the monitoring backend. Parallel engine implementations exist for Go, PHP, TypeScript (on npm), and Rust (on crates.io) - all ports of the same reference semantics, conformance-tested against the shared adversarial corpus.

Python

Package	Role	PyPI
guard-core	Framework-agnostic security engine
guard-agent	Telemetry agent
fastapi-guard	FastAPI / Starlette adapter
flaskapi-guard	Flask adapter
djapi-guard	Django adapter
tornadoapi-guard	Tornado adapter

Go

Go modules published via GitHub releases. Production-ready.

Package	Role	Release
guard-core-go	Go engine
nethttp-guard	net/http adapter
gin-guard	Gin adapter
echo-guard	Echo (v4) adapter
fiber-guard	Fiber (v3) adapter
guard-agent-go	Telemetry agent

PHP

Published on Packagist under the rennf93 vendor. Production-ready.

Package	Role	Packagist
guard-core-php	PHP engine
laravel-guard	Laravel adapter
symfony-guard	Symfony adapter
psr15-guard	PSR-15 adapter
slim-guard	Slim 4 adapter
guard-agent-php	Telemetry agent

TypeScript / JavaScript

Published under the @guardcore npm scope; source in the guard-core-ts monorepo. Production-ready.

Package	Role	npm
	@guardcore/core	Core engine
@guardcore/express	Express adapter
@guardcore/nestjs	NestJS adapter
@guardcore/fastify	Fastify adapter
@guardcore/hono	Hono (edge) adapter
guardagent	Telemetry agent

Rust

Published on crates.io. Production-ready.

Package	Role	crates.io
guard-core-engine	Core engine crate
guard-core-rs	Facade crate (consumer entry point)
actix-guard-rs	Actix Web adapter
axum-guard-rs	Axum adapter
tower-guard-rs	Tower adapter
rocket-guard-rs	Rocket adapter
guard-agent-rs	Telemetry agent

AI Coding Agents

Package	Role	PyPI
guard-core-mcp	MCP server: config validation, docs search, detection sandbox

Features

• IP Whitelisting and Blacklisting: Control access based on IP addresses.
• User Agent Filtering: Block requests from specific user agents.
• Rate Limiting: Limit the number of requests from a single IP.
• Automatic IP Banning: Automatically ban IPs after a certain number of suspicious requests.
• Penetration Attempt Detection: Detect and log potential penetration attempts.
• HTTP Security Headers: Comprehensive security headers management (CSP, HSTS, X-Frame-Options, etc.)
• Custom Logging: Log security events to a custom file.
• Cloud Provider IP Blocking: Block requests from cloud provider IPs (AWS, GCP, Azure).
• IP Geolocation: Use a service like IPInfo.io API to determine the country of an IP address.
• Distributed State Management: (Optional) Redis integration for shared security state across instances
• Flexible Storage: Redis-enabled distributed storage or in-memory storage for single instance deployments

Installation

To install tornadoapi-guard, use pip:

pip install tornadoapi-guard

v1.0.0 release notes

tornadoapi-guard 1.0.0 ships against guard-core >= 3.0.0 and exposes two adapter-side surfaces alongside the upstream fail-secure default.

Upstream fail-secure default

SecurityConfig.fail_secure defaults to True (inherited from guard-core 3.0.0). If any security check raises an unhandled exception, the request is blocked with HTTP 500 instead of falling through. Opt out on deployments that need fail-open behavior:

from tornadoapi_guard import SecurityConfig, SecurityMiddleware

config = SecurityConfig(
    fail_secure=False,
)
middleware = SecurityMiddleware(config=config)

The recommended migration is to keep the new default, surface check exceptions in your monitoring, and fix them at the root.

Reading agent buffer state

SecurityMiddleware.agent_stats exposes the agent's live buffer drop counters and circuit-breaker state without reaching into the agent directly. Wire it into a Tornado-style health-check handler:

import tornado.web
from tornadoapi_guard import SecurityMiddleware


class AgentHealthHandler(tornado.web.RequestHandler):
    async def get(self) -> None:
        middleware: SecurityMiddleware = self.application.settings["security_middleware"]
        self.write(middleware.agent_stats)
# {"enabled": True,
#  "buffer_stats": {"events_dropped": 0, "metrics_dropped": 0, ...},
#  "transport_stats": {"circuit_breaker_state": "CLOSED", ...}}

When the agent is disabled or failed to initialize, the property returns {"enabled": False}. Read it on each scrape — it reflects live counters and is not cached.

Wiring the package version through to the agent

from tornadoapi_guard import SecurityConfig, __version__

config = SecurityConfig(
    enable_agent=True,
    agent_api_key="...",
    agent_guard_version=__version__,
)

__version__ resolves via importlib.metadata.version("tornadoapi_guard") and falls back to "0.0.0+unknown" when the package is not installed (development from source). Pairs with guard-core >= 3.0.0's SecurityConfig.agent_guard_version for SaaS-side telemetry attribution.

Quick Start

import asyncio
import tornado.web
from tornadoapi_guard import SecurityConfig, SecurityHandler, SecurityMiddleware

config = SecurityConfig(
    rate_limit=100,
    auto_ban_threshold=5,
    enable_penetration_detection=True,
)
middleware = SecurityMiddleware(config=config)


class HelloHandler(SecurityHandler):
    async def get(self) -> None:
        self.write({"message": "hello"})


async def main() -> None:
    await middleware.initialize()
    app = tornado.web.Application(
        [(r"/", HelloHandler)],
        security_middleware=middleware,
    )
    app.listen(8000)
    await asyncio.Event().wait()


if __name__ == "__main__":
    asyncio.run(main())

See examples/simple_app/main.py for a full reference application exercising every decorator and security feature.

Building the docs

Full documentation is published at https://guard-core.github.io/tornadoapi-guard/latest/, or build locally with make serve-docs.

Development

# Install dependencies
make install-dev

# Run tests locally
make local-test

# Run linters
make lint

# Fix formatting
make fix

# Run all checks
make check-all

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Author

Renzo Franceschini - contact@guard-core.com .

Acknowledgements

• Tornado
• guard-core
• Redis