Skip to content

code_policy_check

Check code against organizational style guides, best practices, and compliance standards defined in governance policies.

Quick Reference

code_policy_check(
    paths: list,                         # Paths to check
    rules: list = None,                  # Specific rules to check
    compliance_standards: list = None,   # Standards to verify
    generate_report: bool = False        # Generate detailed report
) -> PolicyCheckResult

User Stories

Persona Story Tool Value
🛡️ Marcus (Security Engineer) "Enforce OWASP secure coding standards across the codebase" Compliance automation
🏢 Jennifer (Enterprise Architect) "Enforce HIPAA/SOC2/PCI-DSS compliance rules automatically" Regulatory compliance
🏢 Jennifer (Enterprise Architect) "Generate PDF compliance reports for auditors" Automated compliance documentation
🔧 Chris (OSS Contributor) "Enforce project coding standards automatically" Quality automation

→ See all user stories

Parameters

Parameter Type Required Default Description
paths list[string] Yes - Files or directories to check
rules list[string] No None Specific rules to check
compliance_standards list[string] No None Standards (SOC2, ISO27001, OWASP)
generate_report bool No false Generate detailed compliance report

Response Schema

{
  "data": {
    "violations": [
      {
        "rule": "string",
        "file": "string",
        "line": "integer",
        "message": "string",
        "severity": "string",
        "suggestion": "string"
      }
    ],
    "summary": {
      "files_checked": "integer",
      "total_violations": "integer",
      "by_severity": {
        "error": "integer",
        "warning": "integer",
        "info": "integer"
      },
      "by_rule": {}
    },
    "compliance_status": {
      "standard": "string",
      "status": "string",
      "requirements_met": "integer",
      "requirements_total": "integer"
    },
    "report_path": "string | null"
  },
  "tier_applied": "string",
  "duration_ms": "integer"
}

Built-in Rules

Rule Description Severity
no-hardcoded-secrets No passwords/keys in code Error
no-eval No eval/exec usage Error
no-sql-concat No string concatenation in SQL Error
type-hints-required Functions need type hints Warning
docstring-required Public functions need docstrings Warning
max-function-length Functions < 50 lines Warning
max-complexity Cyclomatic complexity < 10 Warning
no-bare-except No bare except clauses Warning
imports-sorted Imports should be sorted Info

Examples

Basic Policy Check

Check the src directory against our coding standards

{
  "paths": ["/project/src"]
}

codescalpel code-policy-check src/

{
  "data": {
    "violations": [
      {
        "rule": "no-hardcoded-secrets",
        "file": "src/config.py",
        "line": 15,
        "message": "Hardcoded API key detected",
        "severity": "error",
        "suggestion": "Use environment variable: os.environ.get('API_KEY')"
      },
      {
        "rule": "type-hints-required",
        "file": "src/utils.py",
        "line": 28,
        "message": "Function 'process_data' missing type hints",
        "severity": "warning",
        "suggestion": "Add parameter and return type annotations"
      },
      {
        "rule": "docstring-required",
        "file": "src/handlers.py",
        "line": 45,
        "message": "Public function 'handle_request' missing docstring",
        "severity": "warning"
      }
    ],
    "summary": {
      "files_checked": 12,
      "total_violations": 3,
      "by_severity": {
        "error": 1,
        "warning": 2,
        "info": 0
      }
    }
  },
  "tier_applied": "community",
  "duration_ms": 145
}

Check Specific Rules

Check only for security-related policy violations

{
  "paths": ["/project/src"],
  "rules": ["no-hardcoded-secrets", "no-eval", "no-sql-concat"]
}

codescalpel code-policy-check src/ \
  --rules no-hardcoded-secrets,no-eval,no-sql-concat

{
  "data": {
    "violations": [
      {
        "rule": "no-hardcoded-secrets",
        "file": "src/config.py",
        "line": 15,
        "severity": "error"
      },
      {
        "rule": "no-sql-concat",
        "file": "src/db/queries.py",
        "line": 42,
        "message": "SQL query uses string concatenation",
        "severity": "error",
        "suggestion": "Use parameterized queries"
      }
    ],
    "rules_checked": ["no-hardcoded-secrets", "no-eval", "no-sql-concat"],
    "summary": {
      "total_violations": 2,
      "by_rule": {
        "no-hardcoded-secrets": 1,
        "no-sql-concat": 1,
        "no-eval": 0
      }
    }
  }
}

Compliance Standards Check

Check if our code meets OWASP security standards

{
  "paths": ["/project/src"],
  "compliance_standards": ["OWASP"]
}

codescalpel code-policy-check src/ --compliance-standards OWASP

{
  "data": {
    "violations": [
      {
        "rule": "A03:2021-Injection",
        "file": "src/db/queries.py",
        "line": 42,
        "message": "SQL injection vulnerability"
      },
      {
        "rule": "A07:2021-Authentication",
        "file": "src/auth/login.py",
        "line": 28,
        "message": "Password comparison should use constant-time comparison"
      }
    ],
    "compliance_status": {
      "standard": "OWASP Top 10 2021",
      "status": "PARTIAL",
      "requirements_met": 8,
      "requirements_total": 10,
      "failed_requirements": [
        "A03:2021-Injection",
        "A07:2021-Authentication"
      ]
    }
  }
}

Generate Compliance Report

Generate a SOC2 compliance report for audit

{
  "paths": ["/project/src"],
  "compliance_standards": ["SOC2"],
  "generate_report": true
}

codescalpel code-policy-check src/ \
  --compliance-standards SOC2 \
  --generate-report

{
  "data": {
    "compliance_status": {
      "standard": "SOC2 Type II",
      "status": "COMPLIANT",
      "requirements_met": 15,
      "requirements_total": 15
    },
    "report_path": "/project/.code-scalpel/reports/soc2_compliance_2025-02-03.pdf",
    "report_summary": {
      "generated_at": "2025-02-03T14:30:00Z",
      "files_analyzed": 45,
      "total_lines": 12500,
      "security_controls": "PASSED",
      "access_controls": "PASSED",
      "encryption_requirements": "PASSED"
    }
  }
}

Custom Rules

Define custom rules in governance.yaml:

# .code-scalpel/governance.yaml
policies:
  custom_rules:
    - name: "company-logging-required"
      description: "All API handlers must use company logger"
      pattern: "def handle_.*\\(.*\\):"
      required: "company_logger"
      severity: "warning"

    - name: "no-print-statements"
      description: "Use logging instead of print"
      pattern: "print\\("
      severity: "error"
      suggestion: "Use logger.info() instead"

Compliance Standards

Standard Focus Areas
OWASP Security vulnerabilities (Top 10)
SOC2 Security, availability, confidentiality
ISO27001 Information security management
PCI-DSS Payment card data security
HIPAA Healthcare data protection

Tier Differences

This tool is available at all tiers. What differs are the limits and capabilities:

Feature Community Pro Enterprise
Availability ✅ Available ✅ Available ✅ Available
Basic rule checking ✅ ✅ ✅
Built-in rules ✅ ✅ ✅
Max paths 100 1,000 Unlimited
Custom rules Built-in only ✅ Custom supported ✅ Custom supported
OWASP compliance Basic checks only ✅ Full OWASP Top 10 ✅ Full OWASP Top 10
SOC2/ISO27001/HIPAA Not available Not available ✅ All standards
PCI-DSS/GDPR Not available Not available ✅ All standards
Report generation Not available Not available ✅ PDF/HTML reports
Audit logging Not available Not available ✅ Full audit trail

CI/CD Integration

# GitHub Actions
- name: Policy Check
  run: |
    code-scalpel policy check ./src --compliance OWASP

- name: Fail on Errors
  run: |
    ERRORS=$(code-scalpel policy check ./src --json | jq '.summary.by_severity.error')
    if [ "$ERRORS" -gt 0 ]; then
      echo "Policy violations found!"
      exit 1
    fi

Tier Limits

code_policy_check capabilities vary by tier:

Feature Community Pro Enterprise
Max files 100 1,000 Unlimited
Max rules 50 200 Unlimited
Compliance enabled ❌ ❌ ✅
Custom rules ❌ ✅ ✅
Audit trail ❌ ❌ ✅
PDF reports ❌ ❌ ✅
Style guides Basic ✅ Full ✅ Full
Best practices Basic ✅ Full ✅ Full
Compliance standards ❌ ❌ SOC2, ISO, HIPAA

Community Tier

  • ✅ Check code against basic style guides
  • ✅ Enforce best practices (PEP 8, etc.)
  • ✅ Basic rule set (50 rules)
  • ⚠️ Limited to 100 files - Small codebases only
  • ⚠️ Max 50 rules - Basic policy enforcement
  • ❌ No compliance standards (SOC2, ISO, HIPAA)
  • ❌ No custom rule definitions
  • ❌ No audit trail

Pro Tier

  • ✅ All Community features
  • ✅ 1,000 files - Production codebases
  • ✅ 200 rules - Comprehensive policy coverage
  • ✅ Custom rules - Organization-specific policies
  • ✅ Full style guides - All major style guides supported
  • ✅ Report generation - HTML/Markdown reports

Enterprise Tier

  • ✅ All Pro features
  • ✅ Unlimited files and rules - Enterprise-scale enforcement
  • ✅ Compliance standards - SOC2, ISO 27001, HIPAA, PCI-DSS
  • ✅ Audit trail - Track all policy violations over time
  • ✅ PDF reports - Professional compliance reports
  • ✅ Policy versioning - Track policy changes
  • ✅ Exception management - Allow approved violations

Key Difference: Compliance and Scale - Community: 100 files, 50 rules, basic style - Development teams - Pro: 1,000 files, 200 rules, custom policies - Production enforcement - Enterprise: Unlimited, compliance standards, audit trail - Regulated industries

→ See tier comparison

Best Practices

  1. Run early in CI - Catch issues before review
  2. Start with warnings - Graduate to errors
  3. Customize for team - Add project-specific rules
  4. Track over time - Monitor violation trends
  5. Autofix when possible - Some rules have fixers