CLI Reference

The middleBrick CLI lets you run security scans from your terminal, pipe results to scripts, and gate CI/CD builds on security scores.

Installation

npm install -g middlebrick

Requires Node.js 18 or later. Verify the installation:

mb --version

Authentication

mb login

Opens your browser to authenticate with your middleBrick account. Your API key is stored locally in ~/.middlebrick/config.json.

mb login

Alternatively, set the MIDDLEBRICK_API_KEY environment variable to skip interactive login:

export MIDDLEBRICK_API_KEY=mb_your_api_key_here

This is the recommended approach for CI/CD environments where interactive login isn’t possible.

mb logout

Clears stored credentials.

mb logout

Commands

mb scan <url>

Submit a URL for security scanning.

mb scan https://api.example.com/v1/users

Options:

Flag	Description
--spec <url>	OpenAPI/Swagger spec URL for deeper analysis
--context <type>	API context: financial, medical, public, internal
--format <fmt>	Output format: pretty (default), json, table
--wait	Wait for scan to complete and show results (default)
--no-wait	Return immediately with the scan ID

Example output (pretty format):

  middleBrick Security Scan
  ─────────────────────────

  URL:    https://api.example.com/v1/users
  Score:  72 / 100
  Grade:  C

  Findings (7):
  ┌──────────┬──────────────────────────────────┬──────────┐
  │ Severity │ Finding                          │ Category │
  ├──────────┼──────────────────────────────────┼──────────┤
  │ CRITICAL │ No authentication required       │ Auth     │
  │ HIGH     │ PII in response (email, phone)   │ Data     │
  │ HIGH     │ Sequential numeric IDs           │ BOLA     │
  │ MEDIUM   │ No rate limiting detected        │ Rate     │
  │ MEDIUM   │ Missing HSTS header              │ Encrypt  │
  │ LOW      │ Server header exposed            │ Invent   │
  │ INFO     │ API version not in URL           │ Invent   │
  └──────────┴──────────────────────────────────┴──────────┘

  Full report: https://app.middlebrick.com/scan/scan_abc123

More examples:

# Scan with OpenAPI spec
mb scan https://api.example.com/v1/users \
  --spec https://api.example.com/openapi.json

# Financial API with JSON output
mb scan https://api.bank.com/v1/accounts \
  --context financial --format json

# Non-blocking scan — returns immediately with scan ID
mb scan https://api.example.com/v1/users --no-wait

# Pipe JSON output to jq
mb scan https://api.example.com/v1/users --format json | jq '.findings[] | select(.severity == "critical")'

mb scans

List your recent scans with scores and timestamps.

mb scans

Example output:

  Recent Scans
  ────────────
  scan_abc123  72/100 (C)  https://api.example.com/v1/users    2m ago
  scan_def456  91/100 (A)  https://api.example.com/v1/health   1h ago
  scan_ghi789  45/100 (D)  https://staging.example.com/v1/pay  3d ago

mb scan <id>

Retrieve results for a previous scan by ID.

mb scan scan_abc123

Returns the same output format as mb scan <url>, using the stored results.

mb config

View or update CLI configuration.

# View current config
mb config

# Set default output format
mb config set format json

# Set default context
mb config set context financial

Environment Variables

Variable	Description
MIDDLEBRICK_API_KEY	API key (overrides mb login)
MIDDLEBRICK_API_URL	Custom API base URL (default: https://api.middlebrick.com/v1)
NO_COLOR	Disable colored output when set to any value

Exit Codes

The CLI returns meaningful exit codes for CI/CD integration:

Code	Meaning
0	Scan completed successfully (no critical findings)
1	Scan completed with critical findings
2	Scan failed or errored
3	Authentication error

CI/CD Usage

Basic gate — fail on critical findings

mb scan https://api.example.com/v1/users --format json || exit 1

Exit code 1 means critical findings were detected. Your CI pipeline treats this as a failed step.

Custom score threshold

RESULT=$(mb scan https://api.example.com/v1/users --format json)
SCORE=$(echo "$RESULT" | jq '.score')
GRADE=$(echo "$RESULT" | jq -r '.grade')

echo "Security score: $SCORE ($GRADE)"

if [ "$SCORE" -lt 75 ]; then
  echo "FAILED: Score $SCORE is below threshold (75)"
  echo "$RESULT" | jq '.findings[] | select(.severity == "critical" or .severity == "high")'
  exit 1
fi

GitLab CI example

security-scan:
  stage: test
  image: node:20
  script:
    - npm install -g middlebrick
    - mb scan $API_URL --format json --context financial
  variables:
    MIDDLEBRICK_API_KEY: $MIDDLEBRICK_API_KEY

Jenkins Pipeline example

stage('API Security') {
    environment {
        MIDDLEBRICK_API_KEY = credentials('middlebrick-api-key')
    }
    steps {
        sh 'npm install -g middlebrick'
        sh 'mb scan $API_URL --format json'
    }
}

For GitHub Actions, see the dedicated GitHub Action integration, which is simpler than using the CLI in a workflow.