guardrails-cli 0.1.39

Guardrails CLI for scanning repositories

Topcoder Guardrails

⚠️ Security Notice: protobuf CVE-2026-0994

This project requires protobuf<6.0 for compatibility with Google and Semgrep dependencies. All protobuf 5.x versions are currently affected by CVE-2026-0994, and there is no fixed version as of January 2026. If you do not use Google AI packages, you may try protobuf>=6.34.0, but this may break other dependencies. Monitor for updates to dependencies that support protobuf 6.x or a patched 5.x release. Until then, pip-audit will report this known vulnerability, but it is required for compatibility.

Enterprise-grade guardrails for GitHub Copilot workflows: a FastAPI backend, GitHub App integration, and CLI that enforce security, policy, and licensing standards with explainable AI + static analysis.

Deployed URL

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

Quick start (hosted)

1. Open the deployed URL.
2. Go to /settings/ui.
3. Paste your OpenAI API key and save.
4. Create or update a PR in a repo where the GitHub App is installed. Guardrails posts comments/checks automatically.

That is all most users need.

What this delivers

• Hybrid analysis engine: rule-based static checks + AI review with explanations.
• Copilot awareness: stricter handling for AI-generated code paths.
• Policy-based enforcement: advisory, warning, blocking, with override label support.
• License/IP compliance: SPDX/license detection and duplication heuristics.
• GitHub PR + commit integration: check runs, inline comments, and summaries.
• Auditability: audit log export, resolution events, and dashboards.
• Extensible rulepacks: sector-specific YAML rulepacks and repo overrides.

Challenge requirement coverage

• Secure coding guardrails with OWASP/CWE mappings.
• Copilot-aware flagging and stricter enforcement for AI-generated code.
• Configurable coding standards via YAML/JSON repo config.
• AI-assisted PR review with explanations and suggested fixes (security, performance, maintainability).
• License/IP checks (restricted licenses + duplication heuristics).
• Policy-based enforcement modes (advisory, warning, blocking) with override support.
• PR and commit scanning via GitHub App (check runs + inline comments + 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) and custom uploads.

Architecture

• backend/ — FastAPI service, rule engine, AI review, audit logging
• github-app/ — GitHub App integration (PR + commit scanning)
• src/guardrails_cli/ — CLI package for local repo scans
• docs/ — Architecture notes

Security & data handling

• No source code retention beyond analysis. Audit logs store sanitized output only.
• Settings storage is encrypted when a key is configured.
• Data residency can be enforced via repo config + environment variable.

Requirements

CLI

• Python 3.9+

Configuration (backend)

Core settings:

• OPENAI_API_KEY (optional) — used when no per-user key exists
• GUARDRAILS_API_TOKEN (optional) — bearer token required for analysis/scan endpoints when set
• GUARDRAILS_ADMIN_TOKEN (optional) — bearer token required for admin endpoints (audit export, rulepack upload)
• SETTINGS_SCOPE (default: global) — global | user | ip
• SETTINGS_TOKEN (optional) — protects settings endpoints
• REQUIRE_AI_REVIEW_DEFAULT (default: false)

Additional backend settings:

• OPENAI_MODEL (default: gpt-4o-mini)
• AI_REVIEW_MAX_CHARS (default: 12000)
• REQUIRE_AI_REVIEW (default: true)
• CORS_ALLOW_ORIGINS (optional, comma-separated)
• DATA_RESIDENCY (optional, must match repo config if set)
• SECURE_COOKIES (default: false)
• RATE_LIMIT_ENABLED (default: true)
• RATE_LIMIT_RPS (default: 10)
• RATE_LIMIT_BURST (default: 20)
• RATE_LIMIT_WINDOW (default: 10)
• SETTINGS_ENC_KEY (optional, used to encrypt settings)
• SETTINGS_KEY_PATH (optional, generates key if not set)
• SETTINGS_STORE_PATH (default: settings.enc)
• AUDIT_LOG_ENABLED (default: true)
• AUDIT_LOG_STORE_OUTPUT (default: true)
• AUDIT_LOG_PATH (default: /tmp/audit_log.jsonl)
• AUDIT_LOG_MAX_BYTES (default: 5000000)
• AUDIT_LOG_MAX_FILES (default: 5)
• AUDIT_LOG_HMAC_KEY (optional)
• GUARDRAILS_ORG_CONFIG (optional, path to org-level YAML/JSON config)
• SEMGREP_ENABLED (optional, set to true to enable Semgrep static analysis)
• SEMGREP_TIMEOUT (optional, default: 20)

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)
• BACKEND_TOKEN (optional) — bearer token for secured backend endpoints
• OVERRIDE_LABEL (optional, default: guardrails-override)
• MAX_FILES (optional, default: 100)
• MAX_FILE_BYTES (optional, default: 200000)
• USE_ASYNC_SCAN (optional, default: false)
• LOG_LEVEL (optional, default: info)
• AI_GENERATED (optional, set to true to force AI-generated mode)

GitHub App hosting environment (Probot runtime):

• APP_ID (required for webhook-hosted app)
• PRIVATE_KEY (required for webhook-hosted app)
• WEBHOOK_SECRET (required for webhook-hosted app)

GitHub Action environment (recommended for most users):

• GITHUB_TOKEN (required, provided by GitHub Actions)

CLI usage

Install:

pip install guardrails-cli

Scan:

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

Before scanning, save your OpenAI API key in the hosted settings UI (/settings/ui). The CLI uses the hosted backend by default.

If the backend enforces API tokens:

guardrails scan <repo-path> --user <token> --api-token <backend-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

What users must do

• Provide their own OpenAI API key via /settings/ui (hosted).
• Install the CLI only if they want local scans.

Self-hosting

Backend API + Settings UI (Railway or Render)

The backend serves the API and the settings UI at /settings/ui. It is the "main website" that stores configuration and audit logs.

1. Deploy the Dockerfile in the repository root (recommended for Railway/Render).
2. Ensure a persistent volume is mounted for settings.enc and audit logs (see railway.json).
3. Set environment variables listed in the backend configuration section above.
4. Expose PORT (defaults to 8000).

GitHub integration options

You can integrate via GitHub Actions or by hosting a GitHub App webhook server.

Option A: GitHub Actions (no webhook)

1. Copy the workflow in .github/workflows/guardrails.yml into the target repository.
2. Set BACKEND_URL to your hosted backend.
3. If you protect endpoints with GUARDRAILS_API_TOKEN, set BACKEND_TOKEN in the workflow env.
4. No webhook configuration is required.

Recommended non-heuristic AI detection (best option):

1. Add an explicit PR label (e.g., ai-generated or copilot-generated).
2. Configure the label list in .guardrails/config.yml using ai_generated_labels.
3. The GitHub integration will treat labeled PRs as AI-generated without relying on commit message heuristics.

Option B: GitHub App (webhook hosted)

1. Create a GitHub App in your organization settings.
2. Set the webhook URL to https://your-app-host/api/github/webhooks and create a WEBHOOK_SECRET.
3. Permissions: Checks (write), Pull Requests (write), Issues (write), Contents (read).
4. Subscribe to events: pull_request, push.
5. Deploy github-app/ as a Probot app using npm run build and npm run start.
6. Set APP_ID, PRIVATE_KEY, WEBHOOK_SECRET, BACKEND_URL, and BACKEND_TOKEN in the app host.

Non-heuristic AI detection (recommended)

Preferred approach: explicit labels + repo config.

1. Add a PR label in GitHub (e.g., ai-generated).
2. Add this to your repo config file:

ai_generated_labels:
	- ai-generated
	- copilot-generated

Optional overrides:

• Force AI mode for all scans by adding ai_generated: true in the repo config.
• Force AI mode in CI by setting AI_GENERATED=true in the workflow env.

Org-level configuration (optional)

Set GUARDRAILS_ORG_CONFIG to point to a YAML/JSON file. Repo-level .guardrails/config.yml overrides org settings.

Example org config:

policy:
	hardcoded_secret: blocking
	sql_injection_risk: blocking
coding_standards_builtin:
	default:
		naming: true
		logging: true
		error_handling: true

Optional Semgrep integration

If Semgrep is installed on the backend host, set SEMGREP_ENABLED=true to run Semgrep with the auto ruleset.

Local development and testing

Backend local run:

1. cd backend
2. pip install -r requirements.txt
3. uvicorn main:app --reload --host 0.0.0.0 --port 8000

GitHub App local run (webhook mode):

1. cd github-app
2. npm install
3. npm run build
4. APP_ID=... PRIVATE_KEY=... WEBHOOK_SECRET=... BACKEND_URL=http://localhost:8000 npm run start

CLI settings (optional)

guardrails settings --issue-user-token

API endpoints

• GET /health
• GET /
• GET /dashboard
• GET /settings
• POST /settings/token
• GET /settings/token/current
• POST /settings/token/assign
• 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 backend/tests

• GET /report/summary — Audit summary counts