Security Commands

The security command group provides comprehensive security analysis tools for Structum projects, including code vulnerability scanning and dependency auditing.

Overview

Security commands are provided by the structum-cli-tools plugin and require installation:

pip install structum-cli-tools

This adds three security commands to the Structum CLI:

  • scan() - Quick code vulnerability scan (Bandit)

  • audit() - Full audit with dependency check (Bandit + Safety)

  • report() - Generate JSON security report

Commands

security scan

Run static analysis security scan on Python code using Bandit.

Options:

target

Directory or file to scan (default: current directory)

--skip-tests / --include-tests

Skip test files from scanning (default: skip)

Examples:

# Scan entire project
structum security scan

# Scan specific package
structum security scan packages/auth/

# Include test files
structum security scan --include-tests

What It Checks:

  • SQL injection vulnerabilities

  • Hardcoded passwords/secrets

  • Insecure eval()/exec() usage

  • Weak cryptographic practices

  • Shell injection risks

  • Pickle usage (arbitrary code execution)

  • Assert usage in production code

security audit

Comprehensive two-phase security audit: code scan + dependency vulnerabilities.

Options:

--deps / --no-deps

Include dependency vulnerability check (default: yes)

Examples:

# Full audit (recommended for CI/CD)
structum security audit

# Code scan only
structum security audit --no-deps

Phases:

  1. Code Scan (Bandit)

    • Same analysis as security scan

    • Checks all Python source files

  2. Dependency Check (Safety)

    • Queries CVE database

    • Reports known vulnerabilities in dependencies

    • Includes severity levels

security report

Generate machine-readable JSON security report for CI/CD integration.

Options:

--output / -o

Output file path (default: security-report.json)

Examples:

# Default output
structum security report

# Custom path
structum security report --output reports/sec-scan.json

# Use in CI/CD
structum security report -o artifacts/security.json

Report Contents:

  • List of all findings with severity (HIGH/MEDIUM/LOW)

  • File locations and line numbers

  • Confidence levels

  • Remediation suggestions

  • Summary statistics

CI/CD Integration

GitHub Actions Example

name: Security Scan

on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install dependencies
        run: |
          pip install structum-cli-tools

      - name: Security Audit
        run: structum security audit

      - name: Generate Report
        if: failure()
        run: structum security report -o security-report.json

      - name: Upload Report
        if: failure()
        uses: actions/upload-artifact@v3
        with:
          name: security-report
          path: security-report.json

Exit Codes

All security commands use standard exit codes:

  • 0 - No vulnerabilities found

  • 1 - Vulnerabilities detected or tool error

Remediation

When vulnerabilities are found:

  1. Review the Bandit output for severity and confidence

  2. Assess if the vulnerability is a false positive

  3. Fix the code or add # nosec comment if false positive

  4. Re-scan to verify fix

For dependency vulnerabilities:

  1. Check if newer versions available

  2. Update dependencies in pyproject.toml

  3. Test thoroughly after updates

  4. Re-audit to confirm fix

See Also