moko-platform/validate/SECURITY_SCANNING.md

Security Scanning Guide

Version: 01.00.00 | Status: Active | Last Updated: 2026-01-28

Overview

This guide provides instructions for implementing and using the comprehensive security scanning infrastructure required for all MokoStandards repositories.

Quick Start

1. Install CodeQL Workflow

Copy the CodeQL workflow template to your repository:

# From your repository root
mkdir -p .github/workflows
cp templates/workflows/codeql-analysis.yml.template .github/workflows/codeql-analysis.yml

2. Configure Languages

Edit .github/workflows/codeql-analysis.yml and update the language matrix to match your repository:

matrix:
  language: ['python']  # Adjust based on your codebase

Supported languages: cpp, csharp, go, java, javascript, python, ruby

Note: The template currently includes Python. Adjust based on your repository contents.

3. Validate Configuration

Run the validation script to ensure your CodeQL configuration matches your codebase:

python3 scripts/validate/validate_codeql_config.py --repo-path .

4. Run Complete Security Scan

Execute the comprehensive security scan:

python3 scripts/validate/security_scan.py

Security Scan Components

The security scanning infrastructure includes four main components:

1. CodeQL Analysis

Purpose: Static Application Security Testing (SAST) for code vulnerabilities

What it scans:

• SQL injection vulnerabilities
• Cross-site scripting (XSS)
• Path traversal issues
• Command injection
• Authentication bypasses
• And 200+ other security patterns

How to run:

• Automatically runs on push to main/dev/rc branches
• Runs on all pull requests
• Weekly scheduled scan on Mondays at 6:00 AM UTC
• Manual trigger via Actions tab

2. Secret Scanning

Purpose: Detect accidentally committed credentials and API keys

What it scans:

• Private keys (RSA, DSA, EC, SSH)
• AWS access keys
• GitHub tokens
• Slack tokens
• Stripe API keys
• And other sensitive patterns

How to run:

python3 scripts/validate/no_secrets.py .

3. Dependency Checking

Purpose: Identify vulnerable third-party dependencies

What it checks:

• Python packages (requirements.txt, pyproject.toml)
• JavaScript packages (package.json)
• PHP packages (composer.json)
• Ruby gems (Gemfile)
• Go modules (go.mod)

How to run (requires pip-audit):

pip install pip-audit
pip-audit --desc

4. Configuration Validation

Purpose: Ensure CodeQL configuration matches repository contents

What it validates:

• CodeQL workflow exists
• Configured languages match source files
• No misconfigured languages that cause CI failures

How to run:

python3 scripts/validate/validate_codeql_config.py

Comprehensive Security Scan

The security_scan.py script orchestrates all security checks:

Basic Usage

# Scan current directory
python3 scripts/validate/security_scan.py

# Scan specific repository
python3 scripts/validate/security_scan.py --repo-path /path/to/repo

# Verbose output
python3 scripts/validate/security_scan.py --verbose

# Generate JSON report
python3 scripts/validate/security_scan.py --json-output security-report.json

Exit Codes

• 0: All scans passed (no critical issues)
• 1: Security issues found

Report Format

The script generates a comprehensive report showing:

======================================================================
🛡️  SECURITY SCAN REPORT
======================================================================

Status: PASS/FAIL
Total Issues: X
  Critical: X
  High: X

----------------------------------------------------------------------
SCAN RESULTS
----------------------------------------------------------------------

✓ CODEQL: configured
✓ CONFIG: passed
✓ SECRETS: passed
✓ DEPENDENCIES: passed

----------------------------------------------------------------------
RECOMMENDATIONS
----------------------------------------------------------------------
1. [Actionable recommendations if issues found]

======================================================================

CI/CD Integration

GitHub Actions

The security scanning workflows are automatically triggered:

CodeQL Analysis (.github/workflows/codeql-analysis.yml):

• On push to main, dev/, rc/, version/** branches
• On pull requests to main, dev/, rc/ branches
• Weekly schedule: Mondays at 6:00 AM UTC
• Manual workflow dispatch

Results: Available in the Security tab → Code scanning alerts

Pre-commit Hook

Add to .git/hooks/pre-commit:

#!/bin/bash
# Run secret scanning before commit
python3 scripts/validate/no_secrets.py . || exit 1

Pre-push Hook

Add to .git/hooks/pre-push:

#!/bin/bash
# Run comprehensive security scan before push
python3 scripts/validate/security_scan.py || exit 1

Vulnerability Response

When security issues are found:

Critical/High Severity

1. Immediate Action: Stop and assess the issue
2. Triage: Within 4 hours
3. Fix: Within 7 days (critical) or 14 days (high)
4. Notify: Security owner and team

Medium/Low Severity

1. Triage: Within 48 hours
2. Fix: Within 30 days (medium) or 60 days (low)
3. Plan: Include in next sprint/release

Dismissing Alerts

Only dismiss alerts with:

• Clear justification
• Risk assessment
• Compensating controls documented
• Security owner approval

Troubleshooting

CodeQL: "No supported languages found"

Problem: CodeQL workflow fails because configured languages don't exist in repository

Solution: Run validation script and adjust language matrix:

python3 scripts/validate/validate_codeql_config.py
# Update .github/workflows/codeql-analysis.yml with detected languages

Secret Scanner: False Positives

Problem: Secret scanner flags example code or test data

Solution: Add exclusion to scripts/validate/no_secrets.py or update patterns

Dependency Scanner: Tool Not Found

Problem: pip-audit or other scanners not installed

Solution: Install required tools:

pip install pip-audit
npm install -g npm-audit

Best Practices

1. Run Locally Before Pushing

Always run security scans locally before pushing:

python3 scripts/validate/security_scan.py --verbose

2. Keep Dependencies Updated

Regularly update dependencies:

# Python
pip list --outdated
pip-audit

# JavaScript
npm audit
npm update

3. Review Security Alerts Weekly

Check the Security tab weekly for new findings:

• GitHub → Security → Code scanning
• GitHub → Security → Dependabot

4. Use Branch Protection

Require security checks to pass before merge:

• Settings → Branches → Branch protection rules
• Enable "Require status checks to pass"
• Select: CodeQL, Dependency Review

5. Rotate Secrets Immediately

If secrets are detected:

1. Revoke exposed credentials immediately
2. Rotate all related secrets
3. Update applications using the credentials
4. Audit access logs for unauthorized use

Additional Resources

• Security Scanning Policy
• CodeQL Documentation
• GitHub Security Features
• OWASP Top 10

Support

For questions or issues with security scanning:

• Open an issue in this repository
• Contact: security@mokoconsulting.tech
• Slack: #security channel

---

Metadata

Field	Value
Document	Security Scanning Guide
Path	/api/validate/SECURITY_SCANNING.md
Version	01.00.00
Status	Active
Last Updated	2026-01-28
Owner	Moko Consulting