aitbc/docs/8_development/security-scanning.md

Security Scanning Configuration

Overview

This document outlines the security scanning configuration for the AITBC project, including Dependabot setup, Bandit security scanning, and comprehensive CI/CD security workflows.

🔒 Security Scanning Components

1. Dependabot Configuration

File: .github/dependabot.yml

Features:

• Python Dependencies: Weekly updates with conservative approach
• GitHub Actions: Weekly updates for CI/CD dependencies
• Docker Dependencies: Weekly updates for container dependencies
• npm Dependencies: Weekly updates for frontend components
• Conservative Updates: Patch and minor updates allowed, major updates require review

Schedule:

• Frequency: Weekly on Mondays at 09:00 UTC
• Reviewers: @oib
• Assignees: @oib
• Labels: dependencies, [ecosystem], [language]

Conservative Approach:

• Allow patch updates for all dependencies
• Allow minor updates for most dependencies
• Require manual review for major updates of critical dependencies
• Critical dependencies: fastapi, uvicorn, sqlalchemy, alembic, httpx, click, pytest, cryptography

2. Bandit Security Scanning

File: bandit.toml

Configuration:

• Severity Level: Medium and above
• Confidence Level: Medium and above
• Excluded Directories: tests, test_*, pycache, .venv, build, dist
• Skipped Tests: Comprehensive list of skipped test rules for development efficiency
• Output Format: JSON and human-readable reports
• Parallel Processing: 4 processes for faster scanning

Scanned Directories:

• apps/coordinator-api/src
• cli/aitbc_cli
• packages/py/aitbc-core/src
• packages/py/aitbc-crypto/src
• packages/py/aitbc-sdk/src
• tests

3. CodeQL Security Analysis

Features:

• Languages: Python, JavaScript
• Queries: security-extended, security-and-quality
• SARIF Output: Results uploaded to GitHub Security tab
• Auto-build: Automatic code analysis setup

4. Dependency Security Scanning

Python Dependencies:

• Tool: Safety
• Check: Known vulnerabilities in Python packages
• Output: JSON and human-readable reports

npm Dependencies:

• Tool: npm audit
• Check: Known vulnerabilities in npm packages
• Coverage: explorer-web and website packages

5. Container Security Scanning

Tool: Trivy

• Trigger: When Docker files are modified
• Output: SARIF format for GitHub Security tab
• Scope: Container vulnerability scanning

6. OSSF Scorecard

Purpose: Open Source Security Foundation security scorecard

• Metrics: Security best practices compliance
• Output: SARIF format for GitHub Security tab
• Frequency: On every push and PR

🚀 CI/CD Integration

Security Scanning Workflow

File: .github/workflows/security-scanning.yml

Triggers:

• Push: main, develop branches
• Pull Requests: main, develop branches
• Schedule: Daily at 2 AM UTC

Jobs:

1. Bandit Security Scan

   • Matrix strategy for multiple directories
   • Parallel execution for faster results
   • JSON and text report generation
   • Artifact upload for 30 days
   • PR comments with findings

2. CodeQL Security Analysis

   • Multi-language support (Python, JavaScript)
   • Extended security queries
   • SARIF upload to GitHub Security tab

3. Dependency Security Scan

   • Python dependency scanning with Safety
   • npm dependency scanning with audit
   • JSON report generation
   • Artifact upload

4. Container Security Scan

   • Trivy vulnerability scanner
   • Conditional execution on Docker changes
   • SARIF output for GitHub Security tab

5. OSSF Scorecard

   • Security best practices assessment
   • SARIF output for GitHub Security tab
   • Regular security scoring

6. Security Summary Report

   • Comprehensive security scan summary
   • PR comments with security overview
   • Recommendations for security improvements
   • Artifact upload for 90 days

📊 Security Reporting

Report Types

1. Bandit Reports

   • JSON: Machine-readable format
   • Text: Human-readable format
   • Coverage: All Python source directories
   • Retention: 30 days

2. Safety Reports

   • JSON: Known vulnerabilities
   • Text: Human-readable summary
   • Coverage: Python dependencies
   • Retention: 30 days

3. CodeQL Reports

   • SARIF: GitHub Security tab integration
   • Coverage: Python and JavaScript
   • Retention: GitHub Security tab

4. Dependency Reports

   • JSON: npm audit results
   • Coverage: Frontend dependencies
   • Retention: 30 days

5. Security Summary

   • Markdown: Comprehensive summary
   • PR Comments: Direct feedback
   • Retention: 90 days

Security Metrics

• Scan Frequency: Daily automated scans
• Coverage: All source code and dependencies
• Severity Threshold: Medium and above
• Confidence Level: Medium and above
• False Positive Rate: Minimized through configuration

🔧 Configuration Files

bandit.toml

[bandit]
exclude_dirs = ["tests", "test_*", "__pycache__", ".venv"]
severity_level = "medium"
confidence_level = "medium"
output_format = "json"
number_of_processes = 4

.github/dependabot.yml

version: 2
updates:
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "weekly"
      day: "monday"
      time: "09:00"

.github/workflows/security-scanning.yml

name: Security Scanning
on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]
  schedule:
    - cron: '0 2 * * *'

🛡️ Security Best Practices

Code Security

• Input Validation: Validate all user inputs
• SQL Injection: Use parameterized queries
• XSS Prevention: Escape user-generated content
• Authentication: Secure password handling
• Authorization: Proper access controls

Dependency Security

• Regular Updates: Keep dependencies up-to-date
• Vulnerability Scanning: Regular security scans
• Known Vulnerabilities: Address immediately
• Supply Chain Security: Verify package integrity

Infrastructure Security

• Container Security: Regular container scanning
• Network Security: Proper firewall rules
• Access Control: Least privilege principle
• Monitoring: Security event monitoring

📋 Security Checklist

Development Phase

• Code review for security issues
• Static analysis with Bandit
• Dependency vulnerability scanning
• Security testing

Deployment Phase

• Container security scanning
• Infrastructure security review
• Access control verification
• Monitoring setup

Maintenance Phase

• Regular security scans
• Dependency updates
• Security patch application
• Security audit review

🚨 Incident Response

Security Incident Process

1. Detection: Automated security scan alerts
2. Assessment: Security team evaluation
3. Response: Immediate patch deployment
4. Communication: Stakeholder notification
5. Post-mortem: Incident analysis and improvement

Escalation Levels

• Low: Informational findings
• Medium: Security best practice violations
• High: Security vulnerabilities
• Critical: Active security threats

📈 Security Metrics Dashboard

Key Metrics

• Vulnerability Count: Number of security findings
• Severity Distribution: Breakdown by severity level
• Remediation Time: Time to fix vulnerabilities
• Scan Coverage: Percentage of code scanned
• False Positive Rate: Accuracy of security tools

Reporting Frequency

• Daily: Automated scan results
• Weekly: Security summary reports
• Monthly: Security metrics dashboard
• Quarterly: Security audit reports

🔮 Future Enhancements

Planned Improvements

• Dynamic Application Security Testing (DAST)
• Interactive Application Security Testing (IAST)
• Software Composition Analysis (SCA)
• Security Information and Event Management (SIEM)
• Threat Modeling Integration

Tool Integration

• SonarQube: Code quality and security
• Snyk: Dependency vulnerability scanning
• OWASP ZAP: Web application security
• Falco: Runtime security monitoring
• Aqua: Container security platform

📞 Security Contacts

Security Team

• Security Lead: security@aitbc.dev
• Development Team: dev@aitbc.dev
• Operations Team: ops@aitbc.dev

External Resources

• GitHub Security Advisory: https://github.com/advisories
• OWASP Top 10: https://owasp.org/www-project-top-ten/
• CISA Vulnerabilities: https://www.cisa.gov/known-exploited-vulnerabilities-catalog

---

Last Updated: March 3, 2026 Next Review: March 10, 2026 Security Team: AITBC Security Team