guardrails-cli 0.1.0

Guardrails CLI for scanning repositories

Topcoder Guardrails Backend

Overview

This project is a secure, modular backend for code analysis, policy enforcement, and audit logging. It uses FastAPI and includes endpoints for code analysis, health checks, and a dashboard for audit logs.

Features

• REST API for code analysis (/analyze)
• Health check endpoint (/health)
• Audit dashboard (/dashboard)
• Modular rulepacks for different sectors
• Security, coding standards, license/IP, and AI review checks

Requirements

• Python 3.9+
• See backend/requirements.txt for all dependencies

Installation

1. Clone the repository.
2. Navigate to the backend directory:

   cd Topcoder/backend
   

3. (Recommended) Create a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

4. Install dependencies:

   pip install -r requirements.txt
   

Configuration

This app is per-user, not global. Settings are scoped by user token when SETTINGS_SCOPE=user.

Local-only (optional):

• Set OPENAI_API_KEY only if you are running locally and want AI review without using the settings UI/CLI.
• Optional: set REQUIRE_AI_REVIEW=false for local/dev to allow non-AI runs.

Audit logging:

• AUDIT_LOG_ENABLED (default: true)
• AUDIT_LOG_PATH (default: audit_log.jsonl)
• AUDIT_LOG_STORE_OUTPUT (default: true) — store full results in audit log

Data residency:

• DATA_RESIDENCY (optional) — reject requests when repo config requires a different residency

Persistent settings (encrypted):

• SETTINGS_ENC_KEY (required for persistence) — a Fernet key used to encrypt stored settings
• SETTINGS_STORE_PATH (optional) — file path for encrypted storage (default: settings.enc)
• SETTINGS_SCOPE (recommended: user) — user keeps settings per user token
• REQUIRE_AI_REVIEW_DEFAULT (optional) — default AI mode when user settings are not set (default: false)

Running the Server

From the Topcoder/backend directory:

uvicorn main:app --reload --host 127.0.0.1 --port 8000

GitHub App Integration

The GitHub app scans PRs and posts a Guardrails report plus a check run, with inline PR review comments for findings in the diff. It also scans push events and reports results on the latest commit.

Environment variables:

• BACKEND_URL (required): Guardrails API base URL
• OVERRIDE_LABEL (optional): label name that allows blocking overrides (default: guardrails-override)
• MAX_FILES (optional): maximum files per PR to scan (default: 100)
• MAX_FILE_BYTES (optional): max file size in bytes (default: 200000)
• USE_ASYNC_SCAN (optional): enable async scan flow (default: false)

The app reads .guardrails/config.yml|yaml|json from the repo when available to apply sector and policy overrides.

Hosted usage (no repo cloning)

If you deploy the backend as a hosted service, users can supply their own OpenAI key without cloning or installing anything.

Per-user flow (required when SETTINGS_SCOPE=user):

• The UI generates a User Token and stores it locally in the browser
• All settings are saved per token

Optional protection:

• Set SETTINGS_TOKEN to protect the settings endpoints

This enables scanning any connected GitHub repo via the app, or calling the API directly from external tools.

Settings UI:

• Website (main app): https://topcoder-production.up.railway.app
• Open /settings/ui on the website to store the key in the main app.
• Auto-fix default and AI mode can be set in the UI and used by the CLI.
• When SETTINGS_SCOPE=user, the UI generates a per-user token and stores it locally.
• You can also paste an existing token (from CLI) and click “Use User Token”.

Step-by-step (UI only):

1. Open /settings/ui.
2. Click “Generate User Token” (or paste one and click “Use User Token”).
3. Paste your OpenAI API key and click “Save Key”.
4. Choose AI mode and Auto-fix defaults.
5. Use the CLI with the same token to scan any repo.

CLI usage (scan any local repo)

Use the lightweight CLI wrapper to scan any repo from its root:

• Run the CLI in this repo via python guardrails.py scan <repo-path>
• Provide the hosted API URL and API key via flags or environment
• Default hosted URL is https://topcoder-production.up.railway.app
• Set GUARDRAILS_API_URL to override the default and avoid passing --api every time
• Optional --autofix applies safe local fixes and stores backups in .guardrails_backup
• If no API key is detected, the CLI prompts for a key or lets you run in non-AI mode
• Use --no-ai to explicitly disable AI review for that run
• If SETTINGS_ENC_KEY is set locally, the CLI saves the entered key to encrypted storage
• For SETTINGS_SCOPE=user, pass --user <token> or set GUARDRAILS_USER to match the UI token
• If no token is provided, the CLI prompts to paste one or generates a new token

Install without cloning (PyPI):

• pip install guardrails-cli
• Then run guardrails scan <repo-path> from any folder

Quick start (CLI):

1. pip install guardrails-cli
2. guardrails scan . --user <token>
3. When prompted, paste the token from the UI (or press Enter to generate a new one)

Local install from repo (optional):

• Run python install-cli.py from this repo to add guardrails to your PATH
• After that, run guardrails scan <repo-path> from any folder

Publish automation (PyPI):

• Run python publish_cli.py to bump patch version, build, and upload
• Run python publish_cli.py --watch to auto-publish on changes Docker auto-publish:
• Set PUBLISH_CLI=true plus TWINE_USERNAME=__token__ and TWINE_PASSWORD=<pypi-token>

CLI settings (no website required)

You can manage the same settings from the CLI:

• Generate a server key: python guardrails.py settings --generate-key
• Generate a local key: python guardrails.py settings --generate-local-key
• Set API key: python guardrails.py settings --set-api-key <key>
• Set AI mode: python guardrails.py settings --ai-mode require|allow
• Set auto-fix default: python guardrails.py settings --autofix-mode on|off
• Verify settings sync: python guardrails.py settings --verify

Optional flags:

• --api to target a different backend URL
• --token if SETTINGS_TOKEN is enabled on the server
• --user to set X-Guardrails-User for scoped settings (useful behind shared IPs)

GitHub App endpoint

Use the same deployment for the webhook URL:

• Webhook URL: https://topcoder-production.up.railway.app

Scan an entire repository

From the Topcoder/backend directory, run:

python scan_repo.py .. --api https://topcoder-production.up.railway.app --sector finance --output scan_results.json

Notes:

• The scan writes a JSON report to scan_results.json.
• Adjust --api for local (http://127.0.0.1:8000) or hosted usage.
• Use --max-files to limit large repos.

API Endpoints

• GET /health — Health check
• POST /analyze — Analyze code (JSON: { "code": "..." })
• POST /analyze-batch — Analyze multiple files
• POST /scan/async — Queue an asynchronous scan
• GET /scan/status/{job_id} — Check async scan status
• GET /dashboard — View audit dashboard
• GET /audit/export — Export audit log
• GET /report/summary — Audit summary counts
• GET /rulepacks — List rulepacks
• POST /rulepacks — Upload a rulepack
• GET /docs — Interactive API docs (Swagger UI)

Testing

Run all backend tests:

pytest

Manual end-to-end usage (what you actually do):

1. Open /settings/ui and generate a User Token (required when SETTINGS_SCOPE=user).
2. Paste your OpenAI API key and set AI/Auto-fix defaults.
3. From any repo, run guardrails scan . --user <token>.
4. Confirm the scan results in scan_results.json and audit entries in the dashboard.

CLI-only test (no UI):

1. guardrails settings --generate-local-key (optional)
2. guardrails settings --set-api-key <key> --user <token>
3. guardrails settings --ai-mode require --user <token>
4. guardrails scan . --user <token>

Notes

• All dependencies are listed in requirements.txt.
• The dashboard reads from audit_log.jsonl.
• For production, set environment variables securely and use HTTPS.

Changelog

• 2026-01-26: Full test and endpoint verification, requirements and documentation updated.