Skip to content

governance.yaml

Define comprehensive governance policies including security requirements, compliance rules, and approval workflows.

Location

your-project/
└── .code-scalpel/
    └── governance.yaml

Tier Availability

Feature Community Pro Enterprise
Basic governance ✅ ✅ ✅
Security policies ✅ ✅ ✅
Approval workflows — ✅ ✅
Compliance rules — — ✅
Audit requirements — — ✅

Minimal Example

# .code-scalpel/governance.yaml
version: "1.0"
profile: minimal

security:
  require_security_scan: true
  block_critical_vulnerabilities: true

Full Example

# Code Scalpel Governance Configuration
version: "1.0"
profile: restrictive

# =============================================================================
# Security Policies
# =============================================================================
security:
  # Require security scan before code modifications
  require_security_scan: true

  # Block operations if critical vulnerabilities found
  block_critical_vulnerabilities: true

  # Minimum confidence threshold for vulnerability reports
  confidence_threshold: 0.8

  # Vulnerability severity thresholds
  severity_thresholds:
    critical: block      # Block operation
    high: warn           # Warn but allow
    medium: log          # Log only
    low: ignore          # Ignore

  # Taint tracking settings
  taint:
    # Additional taint sources beyond defaults
    custom_sources:
      - "request.json"
      - "request.headers"
      - "os.environ.get"

    # Custom dangerous sinks
    custom_sinks:
      - "subprocess.call"
      - "pickle.loads"
      - "yaml.load"

    # Custom sanitizers (functions that clean data)
    sanitizers:
      - "bleach.clean"
      - "html.escape"
      - "sqlalchemy.text"

# =============================================================================
# Code Modification Policies
# =============================================================================
modifications:
  # Always create backups before modifications
  require_backup: true

  # Require simulate_refactor before update_symbol
  require_simulation: true

  # Block modifications to certain files
  protected_files:
    - "**/__init__.py"
    - "**/migrations/**"
    - "**/config/**"

  # Require approval for modifications to these paths
  approval_required:
    - "src/core/**"
    - "src/security/**"
    - "src/api/**"

  # Maximum lines that can be changed in one operation
  max_lines_per_change: 100

# =============================================================================
# Analysis Policies
# =============================================================================
analysis:
  # Require full project scan before any analysis
  require_project_scan: false

  # Cache analysis results
  enable_cache: true
  cache_ttl_minutes: 30

  # Complexity thresholds
  complexity:
    warning_threshold: 10
    error_threshold: 20
    block_threshold: 30  # Block changes that exceed this

  # Dependency policies
  dependencies:
    # Block analysis if circular imports detected
    block_circular_imports: false

    # Maximum dependency depth to analyze
    max_depth: 10

# =============================================================================
# Compliance Rules (Enterprise)
# =============================================================================
compliance:
  # Enabled compliance standards
  standards:
    - SOC2
    - HIPAA

  # SOC 2 specific rules
  soc2:
    require_audit_logging: true
    require_access_controls: true
    require_encryption: true

  # HIPAA specific rules  
  hipaa:
    require_phi_protection: true
    require_audit_trail: true
    allowed_phi_fields: []  # Block all PHI by default

  # Custom compliance rules
  custom_rules:
    - id: require-error-codes
      description: "All exceptions must have error codes"
      severity: error
      pattern: "raise.*Exception\\([^E]"

    - id: no-print-statements
      description: "Use logging instead of print"
      severity: warning
      pattern: "\\bprint\\s*\\("
      exclude:
        - "tests/**"
        - "scripts/**"

# =============================================================================
# Approval Workflows (Pro+)
# =============================================================================
approvals:
  # Enable approval workflows
  enabled: true

  # Default approvers
  default_approvers:
    - "@security-team"

  # Path-specific approvers
  path_approvers:
    "src/security/**":
      - "@security-lead"
      - "@ciso"
    "src/api/**":
      - "@api-team"
    "src/core/**":
      - "@architecture-team"

  # Auto-approve rules
  auto_approve:
    # Auto-approve test file changes
    - path: "tests/**"
      conditions:
        - "no_new_vulnerabilities"
        - "coverage_maintained"

    # Auto-approve documentation
    - path: "docs/**"
      conditions: []

# =============================================================================
# Audit Settings (Enterprise)
# =============================================================================
audit:
  # Enable audit logging
  enabled: true

  # What to log
  log_operations:
    - analyze_code
    - extract_code
    - update_symbol
    - security_scan
    - cross_file_security_scan

  # Audit log destination
  destinations:
    - type: file
      path: "/var/log/code-scalpel/audit.json"
    - type: syslog
      host: "siem.internal"
      port: 514

  # Retention
  retention_days: 90

  # Include results in audit
  include_results: false  # Results can be large

# =============================================================================
# Notifications
# =============================================================================
notifications:
  # Notify on critical vulnerabilities
  critical_vulnerabilities:
    channels:
      - slack: "#security-alerts"
      - email: "security@company.com"

  # Notify on policy violations
  policy_violations:
    channels:
      - slack: "#dev-alerts"

Configuration Sections

Security

security:
  require_security_scan: true
  block_critical_vulnerabilities: true
  confidence_threshold: 0.8
Setting Type Description
require_security_scan bool Scan before modifications
block_critical_vulnerabilities bool Stop on critical findings
confidence_threshold float Minimum confidence (0.0-1.0)

Modifications

modifications:
  require_backup: true
  require_simulation: true
  protected_files: [...]
Setting Type Description
require_backup bool Always backup before changes
require_simulation bool Run simulate_refactor first
protected_files string[] Files that cannot be modified
approval_required string[] Files requiring approval

Compliance (Enterprise)

compliance:
  standards:
    - SOC2
    - HIPAA

Supported standards: - SOC2 - Service Organization Control 2 - ISO27001 - Information Security Management - HIPAA - Health Insurance Portability - PCI-DSS - Payment Card Industry - GDPR - General Data Protection Regulation

Approvals (Pro+)

approvals:
  enabled: true
  default_approvers: ["@security-team"]

Approvers can be: - GitHub users: @username - GitHub teams: @org/team - Email addresses: user@company.com

Audit (Enterprise)

audit:
  enabled: true
  log_operations: [...]
  destinations: [...]

Log every Code Scalpel operation for compliance.

Governance Profiles

Use pre-defined profiles:

profile: restrictive  # permissive, minimal, default, restrictive

Or override specific settings:

profile: default
security:
  block_critical_vulnerabilities: true  # Override default

Validation

code-scalpel config validate

Next Steps