Policy and Deployment Checks

Capture and compare policy

uv run flasgo routes app.py --policy
uv run flasgo routes app.py --json --output policy.json
uv run flasgo check app.py --deploy
uv run flasgo check app.py --deploy --json
uv run flasgo check app.py --against policy.json --json

routes --json emits a versioned snapshot of registered HTTP and WebSocket routes, authentication backend names, permissions, CSRF methods, CORS policies, quotas, response contracts, application limits, and internal endpoint configuration. It excludes session data, signing keys, metrics credentials, and storage connection strings. Custom permission callables are identified by name; their meaning and application middleware remain application-owned. A snapshot cannot establish that an authentication backend validates credentials correctly or that arbitrary middleware preserves the described policy. Keep snapshots in the development/review workflow, not a public endpoint.

routes --json --output policy.json (or -o policy.json) writes the snapshot atomically, keeping application import output separate from the saved JSON. --output requires --json; omitting it preserves stdout output. Replacing an existing file keeps its permissions; a new file, or one replacing a symlink, uses the process umask. A failed write leaves no temporary file behind.

check --deploy adds warnings for debug mode, disabled host validation, relaxed cookie/CSRF/origin/cache controls, unprotected docs, disabled security logging, and routes without an explicit access declaration. Warnings cause a nonzero exit status. Host check FG002 reports only ENFORCE_ALLOWED_HOSTS=False: in 0.10.0 an ALLOWED_HOSTS entry such as "*" fails at startup instead of being reported as unrestricted. public=True records intentional public access; it does not bypass CSRF, rate limiting, host checks, or existing authorization. An authorization decorator combined with public=True is a contradictory declaration and fails the deployment check. A warning about disabled CSRF requires application review: an API that accepts only explicit bearer credentials differs from an API that also accepts browser cookies.

check --against accepts a routes --json snapshot, reports changed application controls and individual added, removed, or changed routes, and returns nonzero for any change. Review intended changes before replacing the baseline. Text reports identify changed routes by protocol, path, and methods; global changes use their section names. It compares declared policies, not Python code or custom authorization semantics. Input snapshots are limited to 2 MiB. Normal flasgo check app.py retains its registration checks.

Declare intentional public access

from flasgo import Flasgo

app = Flasgo()


@app.get("/health", public=True)
def health():
    return {"status": "ok"}


snapshot = app.policy_snapshot()
assert snapshot["schema_version"] == 1

HTTP and WebSocket decorators accept public=True. Protect other routes with app.authorize(...) or inherited blueprint permissions. Static routes are declared public by the framework. Ordinary routes without either declaration retain their runtime behavior but produce a deployment warning.

A practical review sequence is to run tests, run check --deploy, inspect routes --policy, save a reviewed routes --json baseline, then enforce check --against in CI. Imports execute application initialization, so use the same deliberate configuration as other CLI checks.

Review boundaries

The snapshot includes schema components for declared response models and describes global controls and internal endpoints as well as routes. It excludes secret values, but route paths, permission names, and schemas can still disclose application structure. Keep the artifact in access-controlled review storage.

OWASP Top 10 2025 is security awareness guidance, not a certification supplied by these checks. Application-owned authentication, object and tenant authorization, database queries, middleware, and deployment infrastructure still need review.

Continue with Blueprints and URL Generation and Security and Authentication.