Safeguards Configuration Guide

Table of Contents

1. Security Rules Configuration
2. Pre-commit Hooks
3. GitHub Actions Security Workflow
4. Security Scanning Tools
5. Troubleshooting

Security Rules Configuration

Basic Rule Chain Setup

from safeguards.rules.base import RuleChain
from safeguards.rules.defaults import PermissionGuardrail, SecurityContextRule

chain = RuleChain()
chain.add_rule(rule1)
chain.add_rule(rule2)

Default Rules

1. Permission Guardrail

permission_rule = PermissionGuardrail(
    required_permissions={"read", "write"},
    role_permissions={
        "admin": {"read", "write", "delete"},
        "editor": {"read", "write"},
        "viewer": {"read"},
    }
)

2. Security Context Rule

security_rule = SecurityContextRule(
    required_security_level="medium",  # Options: low, medium, high
    allowed_environments={"prod", "staging", "dev"}
)

3. Resource Limit Rule

resource_rule = ResourceLimitRule(
    max_memory_mb=1024,
    max_cpu_percent=80
)

4. Rate Limit Rule

rate_rule = RateLimitRule(
    max_requests=100,
    time_window_seconds=60
)

Rule Dependencies

Rules can specify dependencies that must be evaluated first:

rule = CustomRule(
    dependencies=[PermissionGuardrail, SecurityContextRule]
)

Rule Priority Levels

• CRITICAL: Must pass, blocks execution
• HIGH: Should pass, may block based on config
• MEDIUM: Warning if fails
• LOW: Informational only

Pre-commit Hooks

Installation

pip install pre-commit
pre-commit install

Available Hooks

1. GitLeaks: Secret detection

   - repo: https://github.com/zricethezav/gitleaks
     rev: v8.18.1
     hooks:
     - id: gitleaks
   

2. Bandit: Python security checks

   - repo: https://github.com/PyCQA/bandit
     rev: 1.7.6
     hooks:
     - id: bandit
   

3. Safety: Dependency scanning

   - repo: https://github.com/Lucas-C/pre-commit-hooks-safety
     rev: v1.3.3
     hooks:
     - id: python-safety-dependencies-check
   

Custom Hook Configuration

See .pre-commit-config.yaml for full configuration options.

GitHub Actions Security Workflow

Workflow Triggers

• Push to main branch
• Pull requests
• Daily scheduled scan

Available Scans

1. GitLeaks for secret detection
2. Safety Check for dependencies
3. Bandit for code analysis
4. Semgrep for pattern matching
5. Dependency Review
6. Snyk vulnerability scanning

Required Secrets

• GITHUB_TOKEN: Automatically provided
• SNYK_TOKEN: Required for Snyk integration

Security Scanning Tools

Bandit Configuration

Configure in .bandit.yml:

exclude_dirs: ['.git', 'tests', 'docs']
skips: []
level: LOW
confidence: LOW

GitLeaks Configuration

Configure in .gitleaks.toml:

[allowlist]
paths = [
    '''.*test.*''',
    '''.*example.*''',
]

[[rules]]
id = "custom-pattern"
regex = '''pattern'''

Semgrep Configuration

Configured in workflow:

- name: Run Semgrep
  run: semgrep ci --config=auto

Troubleshooting

Common Issues

1. Pre-commit Hook Failures
2. Check hook configuration in .pre-commit-config.yaml
3. Run pre-commit run --all-files for details

4. Update hooks: pre-commit autoupdate

5. GitHub Actions Failures

6. Check workflow run logs
7. Verify required secrets are set

8. Check tool-specific configuration files

9. Security Rule Violations

10. Review violation messages
11. Check rule configuration
12. Verify input data format

Best Practices

1. Rule Chain Configuration
2. Order rules by priority
3. Consider dependencies

4. Use appropriate priority levels

5. Security Scanning

6. Regular dependency updates
7. Monitor scan results

8. Address high-priority issues first

9. Custom Rules

10. Follow rule interface
11. Include comprehensive tests
12. Document requirements

Getting Help

• Check GitHub issues
• Review documentation
• Contact maintainers