guardrails-cli 0.1.17

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
• Repo license detection (local scans)
• Cross-file duplicate code detection (batch scans)
• AI review with PR/commit context when available

Requirements

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

Deployed URL

https://topcoder-production.up.railway.app

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.

Railway note (important):

• Railway containers use an ephemeral filesystem on redeploys. If you rely on the settings UI/CLI to store the API key, it will be lost unless you persist the settings file.
• Fix: use a persistent key file + settings file on a Railway volume. Example: attach a volume at /data, then set SETTINGS_KEY_PATH=/data/settings.key and SETTINGS_STORE_PATH=/data/settings.enc. The key file is created on first boot and reused on redeploys.
• If you do not want to persist a file, set OPENAI_API_KEY as an environment variable in Railway so the key is always present after redeploys.

Guardrails Backend

FastAPI-based service that analyzes code, applies policy/rulepacks, and reports results for PRs, commits, and local scans. It ships with a settings UI, audit logging, and a lightweight CLI for scanning any repository.

What it does

• Analyzes code via REST endpoints and returns structured findings.
• Enforces security, coding standards, license/IP, sector rules, and AI review policy.
• Stores audit logs and provides summaries.
• Supports rulepacks and repo-level overrides.
• Integrates with a GitHub App for PR and push scans.

Challenge requirement coverage

• Secure coding guardrails with OWASP/CWE mappings.
• Copilot-aware flagging and stricter handling for AI-generated code.
• Configurable coding standards (YAML/JSON in repo config).
• AI-assisted review with explainable findings.
• License/IP checks with restricted license detection.
• Policy-based enforcement (advisory/warning/blocking) with override label.
• PR/commit scanning via GitHub App with inline comments and summaries.
• Traceability with audit IDs, export, and resolution events.
• Async scan flow for large PRs.
• Pluggable rulepacks per industry (finance, healthcare, public sector, telecom, government).

How people use it

Website-only:

1. Open /settings/ui on your deployment.
2. Save your OpenAI API key.
3. Set AI mode and auto-fix defaults.
4. Use the GitHub App integration or call the API directly.

CLI (most common):

1. pip install guardrails-cli
2. Open /settings/ui once and save your API key.
3. Generate a user token (CLI or UI):
   • CLI: guardrails settings --issue-user-token
   • UI: /settings/ui shows and can regenerate the token
4. Paste a CLI token into /settings/ui if you want to override the auto-generated token for this browser.
5. guardrails scan <repo-path> --user <token> (path optional; defaults to current directory)

Project layout

• backend/ — FastAPI service and rule engine
• github-app/ — GitHub App integration
• src/guardrails_cli/ — Published CLI package
• docs/ — Architecture notes

Requirements

• Python 3.9+
• Dependencies in backend/requirements.txt

Local setup

cd Topcoder/backend
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

Run the server

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

Configuration (environment variables)

Core settings:

• OPENAI_API_KEY (optional) — used when no per-user key exists
• SETTINGS_SCOPE (default: global) — global | user | ip
• SETTINGS_TOKEN (optional) — protects settings endpoints
• SETTINGS_ENC_KEY (recommended) — encrypts persisted settings
• SETTINGS_KEY_PATH (optional) — path to a persistent encryption key file (auto-created when missing)
• SETTINGS_STORE_PATH (default: settings.enc) — encrypted settings file
• REQUIRE_AI_REVIEW_DEFAULT (default: false)

Audit logging:

• AUDIT_LOG_ENABLED (default: true)
• AUDIT_LOG_PATH (default: audit_log.jsonl)
• AUDIT_LOG_STORE_OUTPUT (default: true)
  • Stored output is sanitized to avoid retaining code snippets or patches

Data residency:

• DATA_RESIDENCY (optional)

GitHub App integration

The GitHub App scans PRs and pushes, posts comments/checks, and reads repo overrides from .guardrails/config.yml|yaml|json.

Environment variables:

• BACKEND_URL (required)
• OVERRIDE_LABEL (optional, default: guardrails-override)
• MAX_FILES (optional, default: 100)
• MAX_FILE_BYTES (optional, default: 200000)
• USE_ASYNC_SCAN (optional, default: false)

CLI usage

Install:

pip install guardrails-cli

Scan:

guardrails scan <repo-path> --user <token>
# Or, from inside your repo:
guardrails scan --user <token>

Fix modes:

• Full fix (AI rewrite + safe fixes): guardrails scan --full-fix --user <token>
• Safe fix only: guardrails scan --safe-fix --user <token>
• No fixes: guardrails scan --no-fix --user <token>

Notes:

• Hosted URL: https://topcoder-production.up.railway.app
• Override with GUARDRAILS_API_URL or --api
• Use --autofix to apply safe local fixes
• Use --no-ai to disable AI review for a run

CLI settings (no UI required)

python guardrails.py settings --generate-local-key
python guardrails.py settings --set-api-key <key>
python guardrails.py settings --ai-mode require|allow
python guardrails.py settings --fix-mode full|safe|none
guardrails settings --issue-user-token
python guardrails.py settings --verify

API endpoints

• GET /health
• GET /
• GET /dashboard
• GET /settings
• POST /settings/token
• GET /settings/ui
• POST /settings/api-key
• POST /settings/ai-mode
• POST /settings/autofix-mode
• POST /settings/override-allowed
• POST /analyze
• POST /analyze-batch
• POST /scan/async
• GET /scan/status/{job_id}
• GET /report/summary
• GET /report/trends
• GET /rulepacks
• POST /rulepacks
• GET /audit/export
• POST /audit/resolve
• GET /docs

Testing

pytest

• GET /report/summary — Audit summary counts