// Technical Documentation

BuildFlow Trust CLI

Compliance scanning for GitHub organizations.

Overview

BuildFlow Trust 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 BuildFlow Trust product page.

Installation

Homebrew (Recommended)

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

Direct Download

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

See the Downloads page for all platforms.

Commands

buildflow-trust 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)
buildflow-trust auth login
# Check authentication status
buildflow-trust auth status
# Clear stored credentials
buildflow-trust auth logout
Subcommands:
  • • login — Opens browser to create PAT, stores token in ~/.config/buildflow-trust/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/buildflow-trust/credentials)
  4. GitHub CLI (gh auth token)

buildflow-trust scan

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

# Basic scan
buildflow-trust scan --org your-org
# Scan with config file
buildflow-trust scan --org your-org --config buildflow-trust.json
# Output for SIEM ingestion (JSON Lines)
buildflow-trust scan --org your-org --format jsonl
# Dry run (preview what would be scanned)
buildflow-trust scan --org your-org --dry-run
Flags:
  • • --org, -o — GitHub organization to scan (required)
  • • --config, -c — Path to buildflow-trust.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)

buildflow-trust init

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

$ buildflow-trust init
BuildFlow Trust 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 [buildflow-trust.json]: buildflow-trust.json
Configuration saved to buildflow-trust.json

buildflow-trust validate

Validates a buildflow-trust.json configuration file and displays the parsed settings.

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

buildflow-trust version

Displays the current BuildFlow Trust version.

$ buildflow-trust version
BuildFlow Trust version 0.2.0

Configuration

BuildFlow Trust reads from a buildflow-trust.json file. Generate one with buildflow-trust init or create it manually. The CLI also searches these default locations: buildflow-trust.json, .buildflow-trust.json, config/buildflow-trust.json, ~/.buildflow-trust.json

buildflow-trust.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

BuildFlow Trust OSS includes 5 built-in policies. All are enabled by default. Disable or change severity per-policy in buildflow-trust.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? BuildFlow Trust 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 buildflow-trust 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 BuildFlow Trust 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 BuildFlow Trust
run: |
curl -L https://github.com/Build-Flow-Labs/buildflow-trust-oss/releases/latest/download/buildflow-trust-linux-amd64 -o buildflow-trust
chmod +x buildflow-trust
- name: Run Compliance Scan
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: ./buildflow-trust scan --org your-org

Docker Example

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

Need More?

BuildFlow Trust 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