OMNI-GRC

CLI Guide

Complete guide to using the OMNI-GRC Command-Line Interface (CLI) for automation, scripting, and headless operations.

Overview
Installation
Global Options
Commands Reference
Examples and Use Cases
Scripting and Automation
Output Formats
Best Practices

Overview

The OMNI-GRC CLI provides full programmatic access to all platform features, enabling:

Automation: Schedule scans, generate reports, manage compliance
CI/CD Integration: Integrate security scanning into your pipelines
Scripting: Build custom workflows and automations
Headless Operation: Manage OMNI-GRC without the web UI
Remote Management: Control OMNI-GRC from remote systems

Key Features

✅ Colorful, user-friendly output
✅ JSON output for scripting (--json)
✅ Quiet mode for logs (--quiet)
✅ Comprehensive help system
✅ Interactive prompts when needed
✅ Progress indicators for long operations

Installation

The CLI is included with OMNI-GRC. Access it using:

# Using npm run
npm run cli -- <command> [options]

# Or using the omni-grc command
npm run omni-grc -- <command> [options]

Creating an Alias (Optional)

For convenience, create a shell alias:

# Add to ~/.bashrc or ~/.zshrc
alias omni='cd /path/to/OMNI-GRC && npm run cli --'

# Then use simply:
omni dashboard
omni scan list

Global Options

These options work with all commands:

Option	Description	Example
`-h, --help`	Display help	`omni-grc --help`
`-V, --version`	Show version number	`omni-grc --version`
`--json`	Output in JSON format (machine-readable)	`omni-grc findings --json`
`-q, --quiet`	Suppress banner and non-essential output	`omni-grc scan list --quiet`
`--no-color`	Disable colored output	`omni-grc findings --no-color`
`--api-url <url>`	Override API base URL	`omni-grc --api-url https://grc.company.com/api`
`-v, --verbose`	Enable verbose/debug output	`omni-grc scan run --verbose`

Commands Reference

Authentication

`auth`

Manage CLI authentication credentials.

Sub-commands:

omni-grc auth login              # Login with credentials
omni-grc auth logout             # Clear stored credentials
omni-grc auth status             # Check authentication status
omni-grc auth token              # Display current API token

Example:

$ omni-grc auth login
Email: admin@example.com
Password: ********
✓ Successfully authenticated

Dashboard

`dashboard`

Display a comprehensive summary dashboard in the terminal.

Usage:

omni-grc dashboard [options]

Options:

--refresh <seconds> - Auto-refresh interval (e.g., --refresh 30)
--frameworks <list> - Filter by frameworks (e.g., --frameworks soc2,iso27001)

Output:

Overall compliance percentage
Open findings by severity
Critical vulnerabilities count
Recent scans
Framework compliance breakdown
Risk summary

Example:

$ omni-grc dashboard

╔══════════════════════════════════════════════════════════╗
║               OMNI-GRC Dashboard Summary                 ║
╚══════════════════════════════════════════════════════════╝

Overall Compliance: 72% ▲ +5% from last month
Open Findings: 47 (12 resolved this week)
Critical Vulnerabilities: 3 ⚠️ Requires immediate attention
Scans Today: 8 (Next scan in 2 hours)

Framework Compliance:
┌─────────────────┬──────────┬────────────────────┐
│ Framework       │ Score    │ Controls           │
├─────────────────┼──────────┼────────────────────┤
│ SOC 2 Type II   │ 78%  ███ │ 50/64 compliant    │
│ ISO 27001:2022  │ 65%  ██  │ 60/93 compliant    │
│ HIPAA           │ 82%  ████ │ 37/45 compliant    │
│ PCI-DSS 4.0     │ 45%  █   │ 35/78 compliant    │
└─────────────────┴──────────┴────────────────────┘

Scans

`scan list`

List all security scans with filters.

Usage:

omni-grc scan list [options]

Options:

--status <status> - Filter by status: pending, running, completed, failed
--scanner <name> - Filter by scanner name (e.g., trivy, prowler)
--limit <n> - Limit number of results (default: 50)
--sort <field> - Sort by field: createdAt, name, status

Example:

$ omni-grc scan list --status completed --limit 5

Recent Scans:
┌──────────────────────────┬─────────┬───────────┬──────────┬──────────────┐
│ Name                     │ Scanner │ Status    │ Findings │ Created      │
├──────────────────────────┼─────────┼───────────┼──────────┼──────────────┤
│ API Server Scan          │ Trivy   │ COMPLETED │ 12       │ 2 hours ago  │
│ AWS Production           │ Prowler │ COMPLETED │ 8        │ 5 hours ago  │
│ Backend Repository       │ Semgrep │ COMPLETED │ 5        │ 1 day ago    │
│ All Repositories         │ Gitleaks│ COMPLETED │ 0        │ 1 day ago    │
└──────────────────────────┴─────────┴───────────┴──────────┴──────────────┘

`scan run`

Execute a new security scan.

Usage:

omni-grc scan run --scanner <scanner> --target <target> [options]

Required Options:

--scanner <name> - Scanner to use (see scan scanners)
--target <target> - Scan target (container image, repo URL, cloud account, etc.)

Optional Options:

--name <name> - Custom scan name
--target-type <type> - Target type: container, repository, filesystem, cloud
--wait - Wait for scan to complete
--timeout <seconds> - Timeout for scan completion (default: 600)
--config <json> - Scanner-specific configuration (JSON string)

Examples:

# Container scan with Trivy
omni-grc scan run --scanner trivy --target nginx:latest --wait

# AWS security scan with Prowler
omni-grc scan run --scanner prowler --target aws://prod-account

# Git repository secret scan
omni-grc scan run --scanner gitleaks --target https://github.com/org/repo

# SAST scan with custom config
omni-grc scan run --scanner semgrep --target /path/to/code --config '{"rules":"p/security-audit"}'

`scan scanners`

List all available scanners with their status and capabilities.

Usage:

omni-grc scan scanners [options]

Options:

--category <category> - Filter by category: container, secrets, sast, cloud, network, host
--available - Show only configured/available scanners

Example:

$ omni-grc scan scanners

Available Scanners:
┌─────────────────┬─────────────┬───────────┬──────────────────────────┐
│ Scanner         │ Category    │ Status    │ Capabilities             │
├─────────────────┼─────────────┼───────────┼──────────────────────────┤
│ Trivy           │ Container   │ Available │ Vulnerabilities, IaC     │
│ Prowler         │ Cloud       │ Available │ AWS, Azure, GCP          │
│ Semgrep         │ SAST        │ Available │ Code security analysis   │
│ Gitleaks        │ Secrets     │ Available │ Secret detection         │
│ TruffleHog      │ Secrets     │ Available │ Secret scanning          │
│ Bandit          │ SAST        │ Available │ Python security          │
│ Kube-bench      │ K8s         │ Unavailable│ Kubernetes CIS benchmarks│
│ OWASP ZAP       │ DAST        │ Unavailable│ Web application scanning │
└─────────────────┴─────────────┴───────────┴──────────────────────────┘

`scan show <id>`

Show detailed information about a specific scan.

Usage:

omni-grc scan show <scan-id>

`scan delete <id>`

Delete a scan and its findings.

Usage:

omni-grc scan delete <scan-id> [--force]

`scan cancel <id>`

Cancel a currently running scan.

Usage:

omni-grc scan cancel <scan-id>

Findings

`findings`

List and filter security findings.

Usage:

omni-grc findings [options]

Options:

--severity <levels> - Filter by severity: critical, high, medium, low, info (comma-separated)
--status <status> - Filter by status: open, in_progress, resolved, false_positive
--scanner <name> - Filter by scanner
--target <target> - Filter by target
--limit <n> - Limit results (default: 50)
--sort <field> - Sort by: severity, createdAt, updatedAt

Examples:

# List all critical and high severity findings
omni-grc findings --severity critical,high

# List open findings from Trivy
omni-grc findings --status open --scanner trivy

# Get findings in JSON for scripting
omni-grc findings --severity critical --json

# Output:
Critical & High Severity Findings:
┌──────────┬────────────────────────────┬────────────┬─────────┬────────────┐
│ Severity │ Finding                    │ Target     │ Scanner │ First Seen │
├──────────┼────────────────────────────┼────────────┼─────────┼────────────┤
│ CRITICAL │ CVE-2024-1234: OpenSSL RCE │ api-server │ Trivy   │ 2 days ago │
│ HIGH     │ S3 Bucket Public Access    │ prod-data  │ Prowler │ 5 days ago │
│ HIGH     │ SQL Injection Vulnerability│ web-app    │ Semgrep │ 1 week ago │
└──────────┴────────────────────────────┴────────────┴─────────┴────────────┘

`findings show <id>`

Display detailed information about a specific finding.

Usage:

omni-grc findings show <finding-id>

Compliance

`compliance status`

Show compliance status across all or specific frameworks.

Usage:

omni-grc compliance status [options]

Options:

--framework <id> - Filter by framework: soc2, iso27001, hipaa, pcidss, nist_csf, gdpr, fedramp, cmmc
--details - Show detailed control breakdown

Example:

$ omni-grc compliance status --framework soc2

SOC 2 Type II Compliance Status:

Overall Compliance: 78% (50 of 64 controls)

Control Categories:
┌────────────────────┬──────────┬───────────────┬──────────────┐
│ Category           │ Score    │ Implemented   │ Outstanding  │
├────────────────────┼──────────┼───────────────┼──────────────┤
│ Control Environment│ 85%  ████│ 11/13         │ 2            │
│ Logical Access     │ 92%  ████│ 23/25         │ 2            │
│ System Operations  │ 70%  ███ │ 14/20         │ 6            │
│ Change Management  │ 50%  ██  │ 2/4           │ 2            │
└────────────────────┴──────────┴───────────────┴──────────────┘

Priority Actions:
1. Implement MFA for all users (CC6.2)
2. Configure automated backups (CC7.1)
3. Document change management process (CC8.1)

`compliance controls`

List all compliance controls with filters.

Usage:

omni-grc compliance controls [options]

Options:

--framework <id> - Filter by framework
--status <status> - Filter by status: not_started, in_progress, implemented, needs_review
--automation <level> - Filter by automation: manual, partial, full
--category <category> - Filter by control category

Example:

$ omni-grc compliance controls --framework soc2 --status not_started

SOC 2 Controls - Not Started:
┌────────┬────────────────────────────┬──────────────┬────────────┐
│ ID     │ Title                      │ Category     │ Automation │
├────────┼────────────────────────────┼──────────────┼────────────┤
│ CC1.2  │ Board Independence         │ Governance   │ Manual     │
│ CC8.1  │ Change Management Process  │ Change Mgmt  │ Partial    │
└────────┴────────────────────────────┴──────────────┴────────────┘

`compliance gaps`

Show compliance gaps and recommendations.

Usage:

omni-grc compliance gaps [options]

Options:

--framework <id> - Focus on specific framework
--priority <level> - Filter by priority: critical, high, medium, low

Reports

`report templates`

List all available report templates.

Usage:

omni-grc report templates [options]

Options:

--category <category> - Filter by category: executive, compliance, security, risk, audit, asset

Example:

$ omni-grc report templates

Available Report Templates:
┌─────────────────────────┬──────────────┬────────────────────────┐
│ Template                │ Category     │ Description            │
├─────────────────────────┼──────────────┼────────────────────────┤
│ executive_summary       │ Executive    │ High-level overview    │
│ board_report            │ Executive    │ Board presentation     │
│ compliance_summary      │ Compliance   │ Multi-framework status │
│ framework_assessment    │ Compliance   │ Single framework deep  │
│ control_gap_analysis    │ Compliance   │ Gap identification     │
│ security_findings       │ Security     │ Vulnerability report   │
│ remediation_tracker     │ Security     │ Fix tracking           │
│ risk_register           │ Risk         │ Risk documentation     │
│ audit_evidence_package  │ Audit        │ Auditor-ready evidence │
│ asset_inventory         │ Asset        │ IT asset listing       │
└─────────────────────────┴──────────────┴────────────────────────┘

`report generate`

Generate a compliance or security report.

Usage:

omni-grc report generate --template <template> [options]

Required Options:

-t, --template <name> - Report template to use

Optional Options:

-f, --format <format> - Output format: pdf, csv, json, xlsx (default: pdf)
--framework <id> - Include specific framework(s)
--output <path> - Output file path
--email <addresses> - Email report to addresses (comma-separated)

Examples:

# Generate executive summary PDF
omni-grc report generate -t executive_summary -f pdf

# Generate SOC 2 compliance report
omni-grc report generate -t framework_assessment --framework soc2

# Generate and email findings report
omni-grc report generate -t security_findings -f pdf --email security@company.com

# Generate CSV export of assets
omni-grc report generate -t asset_inventory -f csv --output assets.csv

Assets

`assets`

List and manage IT asset inventory.

Usage:

omni-grc assets [options]

Options:

--type <type> - Filter by type: server, workstation, network_device, cloud_resource, application, database, container
--status <status> - Filter by status: active, inactive, decommissioned
--environment <env> - Filter by environment: production, staging, development
--criticality <level> - Filter by criticality: critical, high, medium, low

Example:

$ omni-grc assets --type server --environment production

Production Servers:
┌────────────────────┬─────────────┬────────────┬─────────────┐
│ Name               │ IP Address  │ Owner      │ Criticality │
├────────────────────┼─────────────┼────────────┼─────────────┤
│ api-server-prod    │ 10.0.1.10   │ DevOps     │ Critical    │
│ db-server-primary  │ 10.0.1.20   │ Database   │ Critical    │
│ web-server-1       │ 10.0.2.10   │ Frontend   │ High        │
└────────────────────┴─────────────┴────────────┴─────────────┘

Risks

`risks`

List and manage the risk register.

Usage:

omni-grc risks [options]

Options:

--level <level> - Filter by risk level: critical, high, medium, low
--status <status> - Filter by status: identified, assessed, mitigated, accepted
--treatment <treatment> - Filter by treatment: mitigate, transfer, accept, avoid

Example:

$ omni-grc risks --level critical,high

High & Critical Risks:
┌──────────┬────────────────────────────┬────────┬──────────┬────────────┐
│ Level    │ Risk                       │ Score  │ Status   │ Owner      │
├──────────┼────────────────────────────┼────────┼──────────┼────────────┤
│ CRITICAL │ Data Breach via API        │ 25/25  │ Mitigating│ CISO       │
│ HIGH     │ Ransomware Attack          │ 20/25  │ Assessed │ Security   │
│ HIGH     │ Third-party Vendor Breach  │ 16/25  │ Accepted │ Risk Mgmt  │
└──────────┴────────────────────────────┴────────┴──────────┴────────────┘

`risks matrix`

Display an interactive risk matrix visualization.

Usage:

omni-grc risks matrix

Alerts

`alerts`

List alert configurations.

Usage:

omni-grc alerts [options]

Options:

--enabled - Show only enabled alerts
--type <type> - Filter by alert type (see alerts types)
--channel <channel> - Filter by channel: email, slack, teams, webhook, pagerduty

Example:

$ omni-grc alerts --enabled

Active Alert Configurations:
┌────────────────────────┬─────────────────────┬──────────────────┐
│ Name                   │ Type                │ Channels         │
├────────────────────────┼─────────────────────┼──────────────────┤
│ Critical Findings      │ new_critical_finding│ Slack, Email     │
│ Compliance Drop        │ compliance_threshold│ Email            │
│ Scan Failures          │ scan_failed         │ Slack, PagerDuty │
└────────────────────────┴─────────────────────┴──────────────────┘

`alerts create`

Create a new alert configuration.

Usage:

omni-grc alerts create --name <name> --type <type> [options]

Required Options:

--name <name> - Alert name
--type <type> - Alert type (see alerts types)

Optional Options:

--email <addresses> - Email recipients (comma-separated)
--slack <webhook> - Slack webhook URL
--teams <webhook> - Microsoft Teams webhook URL
--webhook <url> - Custom webhook URL
--pagerduty <key> - PagerDuty integration key

Example:

# Create critical findings alert with Slack
omni-grc alerts create \
  --name "Critical Findings Alert" \
  --type new_critical_finding \
  --slack https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX \
  --email security@company.com

`alerts test <id>`

Send a test notification for an alert.

Usage:

omni-grc alerts test <alert-id>

`alerts types`

List all available alert types and their descriptions.

Usage:

omni-grc alerts types

Output:

Available Alert Types:
┌──────────────────────┬───────────────────────────────────┐
│ Type                 │ Description                       │
├──────────────────────┼───────────────────────────────────┤
│ new_critical_finding │ New critical severity finding     │
│ compliance_threshold │ Compliance score drops below X%   │
│ scan_failed          │ Scan execution failed             │
│ scan_completed       │ Scan finished                     │
│ control_status_change│ Control status changed            │
│ risk_score_change    │ Risk score increased              │
│ certificate_expiry   │ SSL/TLS cert expiring soon        │
│ sla_breach           │ Finding not resolved within SLA   │
│ custom               │ Custom condition-based alert      │
└──────────────────────┴───────────────────────────────────┘

Server

`server dev`

Start the development server.

Usage:

omni-grc server dev [--port <port>]

`server start`

Start the production server.

Usage:

omni-grc server start [--port <port>]

`server db migrate`

Run database migrations.

Usage:

omni-grc server db migrate

`server db seed`

Seed the database with initial data.

Usage:

omni-grc server db seed

TUI

`tui`

Launch the Terminal User Interface.

Usage:

omni-grc tui

See TUI Guide for detailed TUI documentation.

Examples and Use Cases

Use Case 1: Daily Security Scan

#!/bin/bash
# daily-scan.sh - Run daily security scans

# Container scan
omni-grc scan run --scanner trivy --target myapp:latest --wait

# Secret scan
omni-grc scan run --scanner gitleaks --target https://github.com/org/repo --wait

# Cloud scan
omni-grc scan run --scanner prowler --target aws://prod-account --wait

# Check for critical findings
CRITICAL=$(omni-grc findings --severity critical --json | jq '.findings | length')

if [ "$CRITICAL" -gt 0 ]; then
  echo "⚠️  Found $CRITICAL critical findings!"
  # Send notification
  omni-grc alerts test alert-id-here
fi

Use Case 2: Compliance Report Generation

#!/bin/bash
# monthly-compliance-report.sh

# Generate compliance reports for all frameworks
for framework in soc2 iso27001 hipaa pcidss; do
  omni-grc report generate \
    -t framework_assessment \
    --framework $framework \
    -f pdf \
    --output "/reports/$(date +%Y-%m)/${framework}-report.pdf"
done

# Generate executive summary
omni-grc report generate \
  -t executive_summary \
  -f pdf \
  --email ceo@company.com,ciso@company.com

Use Case 3: CI/CD Integration

# .github/workflows/security-scan.yml
name: Security Scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Run Security Scan
        run: |
          npm run cli -- scan run \
            --scanner semgrep \
            --target . \
            --wait \
            --json > scan-results.json
      
      - name: Check for Critical Findings
        run: |
          CRITICAL=$(jq '.findings | map(select(.severity == "critical")) | length' scan-results.json)
          if [ "$CRITICAL" -gt 0 ]; then
            echo "::error::Found $CRITICAL critical security findings"
            exit 1
          fi

Use Case 4: Asset Discovery

#!/bin/bash
# discover-assets.sh - Discover and inventory assets

# Export current assets
omni-grc assets --format json > /tmp/current-assets.json

# Scan AWS for new resources
aws ec2 describe-instances --query 'Reservations[].Instances[].[InstanceId,PrivateIpAddress,Tags[?Key==`Name`].Value|[0]]' --output json > /tmp/aws-instances.json

# TODO: Parse and import new assets via API

Scripting and Automation

JSON Output

All commands support --json flag for machine-readable output:

# Get findings as JSON
omni-grc findings --severity critical --json

# Parse with jq
omni-grc findings --json | jq '.findings[] | select(.status == "open")'

# Count findings by severity
omni-grc findings --json | jq '.findings | group_by(.severity) | map({severity: .[0].severity, count: length})'

Exit Codes

The CLI uses standard exit codes:

0 - Success
1 - General error
2 - Invalid arguments
3 - Authentication error
4 - Not found
5 - Timeout

Environment Variables

Override defaults with environment variables:

export OMNI_GRC_API_URL="https://grc.company.com/api"
export OMNI_GRC_TOKEN="your-api-token"
export OMNI_GRC_OUTPUT_FORMAT="json"

omni-grc dashboard  # Uses environment configuration

Output Formats

Table Output (Default)

Human-readable tables with colors and formatting.

JSON Output

Machine-readable JSON for scripting:

{
  "findings": [
    {
      "id": "finding-123",
      "severity": "critical",
      "title": "CVE-2024-1234: OpenSSL RCE",
      "target": "api-server:latest",
      "scanner": "trivy",
      "status": "open",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "timestamp": "2024-01-01T12:00:00Z"
}

CSV Output

For select commands (reports, assets):

omni-grc assets --format csv > assets.csv

Best Practices

1. Use Automation

Schedule regular scans and report generation:

# Add to crontab
0 2 * * * /path/to/omni-grc scan run --scanner trivy --target myapp:latest
0 8 1 * * /path/to/omni-grc report generate -t executive_summary --email ceo@company.com

2. Version Control Your Scripts

Store CLI scripts in version control:

scripts/
├── daily-scans.sh
├── weekly-reports.sh
└── compliance-check.sh

3. Use –json for Parsing

Always use --json when parsing output in scripts:

# Good
CRITICAL_COUNT=$(omni-grc findings --severity critical --json | jq '.total')

# Bad (fragile, depends on formatting)
CRITICAL_COUNT=$(omni-grc findings --severity critical | grep -c CRITICAL)

4. Error Handling

Always check exit codes:

if omni-grc scan run --scanner trivy --target myapp:latest --wait; then
  echo "Scan completed successfully"
else
  echo "Scan failed with exit code $?"
  exit 1
fi

5. Quiet Mode for Cron

Use --quiet to suppress banner in cron jobs:

omni-grc scan list --quiet --json > /var/log/omni-grc/scans.json

Troubleshooting

Issue: “Connection refused”

Solution: Ensure the server is running:

omni-grc server dev

Issue: “Unauthorized”

Solution: Authenticate first:

omni-grc auth login

Issue: “Scanner not available”

Solution: Check scanner availability:

omni-grc scan scanners

Install required scanner tools.

Next Steps

TUI Guide - Interactive terminal interface
API Reference - Direct API access
Scanner Integration - Configure security tools
Troubleshooting - Common issues and solutions

Need Help? Check our GitHub Discussions or file an issue.

OMNI-GRC

CLI Guide

Table of Contents

Overview

Key Features

Installation

Creating an Alias (Optional)

Global Options

Commands Reference

Authentication

auth

Dashboard

dashboard

Scans

scan list

scan run

scan scanners

scan show <id>

scan delete <id>

scan cancel <id>

Findings

findings

findings show <id>

Compliance

compliance status

compliance controls

compliance gaps

Reports

report templates

report generate

Assets

assets

Risks

risks

risks matrix

Alerts

alerts

alerts create

alerts test <id>

alerts types

Server

server dev

server start

server db migrate

server db seed

TUI

tui

Examples and Use Cases

Use Case 1: Daily Security Scan

Use Case 2: Compliance Report Generation

Use Case 3: CI/CD Integration

Use Case 4: Asset Discovery

Scripting and Automation

JSON Output

Exit Codes

Environment Variables

Output Formats

Table Output (Default)

JSON Output

CSV Output

Best Practices

1. Use Automation

2. Version Control Your Scripts

3. Use –json for Parsing

4. Error Handling

5. Quiet Mode for Cron

Troubleshooting

Issue: “Connection refused”

Issue: “Unauthorized”

Issue: “Scanner not available”

Next Steps

`auth`

`dashboard`

`scan list`

`scan run`

`scan scanners`

`scan show <id>`

`scan delete <id>`

`scan cancel <id>`

`findings`

`findings show <id>`

`compliance status`

`compliance controls`

`compliance gaps`

`report templates`

`report generate`

`assets`

`risks`

`risks matrix`

`alerts`

`alerts create`

`alerts test <id>`

`alerts types`

`server dev`

`server start`

`server db migrate`

`server db seed`

`tui`