// Technical Documentation

BuildGuard CLI

Compliance scanning for GitHub organizations.

Overview

BuildGuard is a Go-based CLI that scans GitHub organizations for compliance violations. The open-source version includes 5 built-in policies covering Docker security, code ownership, secret exposure, branch protection, and SOX separation of duties.

Results are displayed in a human-readable table format or exported as JSON Lines for SIEM ingestion (Splunk, Wazuh, Elastic).

For the full product overview including additional policies and framework mappings, see the BuildGuard product page.

Installation

Homebrew (Recommended)

terminal
# Install via Homebrew
brew install build-flow-labs/buildguard/buildguard
# Verify installation
buildguard version

Direct Download

terminal
# Download binary (macOS Apple Silicon)
curl -L https://github.com/Build-Flow-Labs/buildguard-oss/releases/latest/download/buildguard-darwin-arm64 -o buildguard
chmod +x buildguard
sudo mv buildguard /usr/local/bin/
# Verify installation
buildguard version

See the Downloads page for all platforms.

Commands

buildguard auth

Manage GitHub authentication. Opens your browser to create a GitHub Personal Access Token with the required scopes (repo, read:org) pre-selected, then stores it securely.

# Authenticate (opens browser)
buildguard auth login
# Check authentication status
buildguard auth status
# Clear stored credentials
buildguard auth logout
Subcommands:
  • • login — Opens browser to create PAT, stores token in ~/.config/buildguard/credentials
  • • status — Show current authentication status and token source
  • • logout — Remove stored credentials
Token Resolution Order:
  1. GITHUB_TOKEN environment variable
  2. BUILDGUARD_TOKEN environment variable
  3. Stored credentials (~/.config/buildguard/credentials)
  4. GitHub CLI (gh auth token)

buildguard scan

Runs a compliance audit across all repositories in a GitHub organization. Evaluates 5 built-in policies and displays a compliance summary.

# Basic scan
buildguard scan --org your-org
# Scan with config file
buildguard scan --org your-org --config buildguard.json
# Output for SIEM ingestion (JSON Lines)
buildguard scan --org your-org --format jsonl
# Dry run (preview what would be scanned)
buildguard scan --org your-org --dry-run
Flags:
  • • --org, -o — GitHub organization to scan (required)
  • • --config, -c — Path to buildguard.json configuration file
  • • --format, -f — Output format: pretty (default) or jsonl
  • • --dry-run — Run without making changes
Output Formats:
  • • pretty — Human-readable table with compliance score and policy breakdown
  • • jsonl — JSON Lines format for SIEM ingestion (Wazuh, Splunk, Elastic)

buildguard init

Interactive setup wizard that creates a buildguard.json configuration file. Prompts for organization name, default branch, and per-policy enablement.

$ buildguard init
BuildGuard Configuration Wizard
GitHub Organization name: acme-corp
Default branch [main]: main
Enable Docker root user check (POL-SEC-01)? [Y/n]: Y
Enable CODEOWNERS check (POL-GOV-02)? [Y/n]: Y
Enable secret exposure check (POL-SEC-03)? [Y/n]: Y
Enable branch protection check (POL-SEC-04)? [Y/n]: Y
Enable SOX separation check (POL-SOX-01)? [Y/n]: Y
Configuration file path [buildguard.json]: buildguard.json
Configuration saved to buildguard.json

buildguard validate

Validates a buildguard.json configuration file and displays the parsed settings.

$ buildguard validate --config buildguard.json
Validating buildguard.json...
Configuration is valid! (5/5 policies enabled)
Flags:
  • • --config, -c — Path to the configuration file to validate (defaults to buildguard.json)

buildguard version

Displays the current BuildGuard version.

$ buildguard version
BuildGuard version 0.2.0

Configuration

BuildGuard reads from a buildguard.json file. Generate one with buildguard init or create it manually. The CLI also searches these default locations: buildguard.json, .buildguard.json, config/buildguard.json, ~/.buildguard.json

buildguard.json
{
"organization": {
"name": "your-org",
"default_branch": "main",
"fallback_branches": ["master", "develop"]
},
"policies": {
"docker_root_user": {
"enabled": true,
"severity": "critical"
},
"code_owners": {
"enabled": true,
"severity": "medium"
},
"secret_exposure": {
"enabled": true,
"severity": "critical",
"patterns": [".env", ".env.local", "credentials.json"]
},
"branch_protection": {
"enabled": true,
"severity": "high",
"min_reviewers": 1,
"require_dismiss_stale": true,
"require_admin_enforcement": true
},
"sox_separation": {
"enabled": true,
"severity": "critical"
}
}
}
Configuration Options:
  • • organization.fallback_branches — Branches to check if default_branch doesn't exist
  • • secret_exposure.patterns — Additional file patterns to check for secrets
  • • branch_protection.min_reviewers — Minimum required reviewers (default: 1)
  • • branch_protection.require_dismiss_stale — Require stale review dismissal
  • • branch_protection.require_admin_enforcement — Require admins to follow rules

Built-in Policies

BuildGuard OSS includes 5 built-in policies. All are enabled by default. Disable or change severity per-policy in buildguard.json.

ID Name Severity Description
POL-SEC-01Docker Root UserCriticalDetects Dockerfiles running as root user
POL-GOV-02CODEOWNERSMediumEnforces presence of CODEOWNERS file
POL-SEC-03Secret ExposureCriticalPrevents secrets from being committed
POL-SEC-04Branch ProtectionHighValidates branch protection rules are enabled
POL-SOX-01SOX SeparationCriticalEnforces separation of duties for SOX compliance

Need more policies? BuildGuard Team and Enterprise include 20+ policies with framework mappings (SOC2, SOX, NIST 800-53, ISO 27001, PCI-DSS, FedRAMP, CIS, HIPAA). View pricing →

Environment Variables

GITHUB_TOKEN GitHub access token (optional if using buildguard auth login)
BUILDGUARD_TOKEN Alternative to GITHUB_TOKEN
BUILDGUARD_ORG Default organization name (overridden by --org flag)
BUILDGUARD_DEFAULT_BRANCH Default branch to check (defaults to main)

CI Integration

Run BuildGuard in your CI pipeline using the pre-built binaries or Docker image.

GitHub Actions Example

.github/workflows/compliance.yml
name: Compliance Scan
on:
schedule:
- cron: '0 6 * * *' # Daily at 6am
workflow_dispatch:
jobs:
scan:
runs-on: ubuntu-latest
steps:
- name: Install BuildGuard
run: |
curl -L https://github.com/Build-Flow-Labs/buildguard-oss/releases/latest/download/buildguard-linux-amd64 -o buildguard
chmod +x buildguard
- name: Run Compliance Scan
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: ./buildguard scan --org your-org

Docker Example

terminal
# Run with Docker
docker run --rm -e GITHUB_TOKEN=$GITHUB_TOKEN \
buildflowlabs/buildguard scan --org your-org
# Output JSONL for SIEM ingestion
docker run --rm -e GITHUB_TOKEN=$GITHUB_TOKEN \
buildflowlabs/buildguard scan --org your-org --format jsonl \
>> /var/log/buildguard/scan.log

Need More?

BuildGuard Team and Enterprise include:

  • • 20+ policies with auto-remediation
  • • Framework mappings (SOC2, SOX, NIST, ISO 27001, PCI-DSS, FedRAMP, CIS, HIPAA)
  • • HTML, JSON, and PDF reports
  • • PostgreSQL evidence ledger
  • • Web dashboard
  • • Slack/email notifications
View Pricing Contact Sales