Charon/docs/security/archive/codeql-scanning.md

CodeQL Security Scanning Guide

Overview

Charon uses GitHub's CodeQL for static application security testing (SAST). CodeQL analyzes code to find security vulnerabilities and coding errors.

Quick Start

Run CodeQL Locally (CI-Aligned)

Via VS Code Tasks:

1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Type "Tasks: Run Task"
3. Select:
   • Security: CodeQL Go Scan (CI-Aligned) - Scan backend
   • Security: CodeQL JS Scan (CI-Aligned) - Scan frontend
   • Security: CodeQL All (CI-Aligned) - Scan both

Via Pre-Commit:

# Quick security check (govulncheck - 5s)
pre-commit run security-scan --all-files

# Full CodeQL scan (2-3 minutes)
pre-commit run codeql-go-scan --all-files
pre-commit run codeql-js-scan --all-files
pre-commit run codeql-check-findings --all-files

Via Command Line:

# Go scan
codeql database create codeql-db-go --language=go --source-root=backend --overwrite
codeql database analyze codeql-db-go \
  codeql/go-queries:codeql-suites/go-security-and-quality.qls \
  --format=sarif-latest --output=codeql-results-go.sarif

# JavaScript/TypeScript scan
codeql database create codeql-db-js --language=javascript --source-root=frontend --overwrite
codeql database analyze codeql-db-js \
  codeql/javascript-queries:codeql-suites/javascript-security-and-quality.qls \
  --format=sarif-latest --output=codeql-results-js.sarif

View Results

Method 1: VS Code SARIF Viewer (Recommended)

1. Install extension: MS-SarifVSCode.sarif-viewer
2. Open codeql-results-go.sarif or codeql-results-js.sarif
3. Navigate findings with inline annotations

Method 2: Command Line (jq)

# Summary
jq '.runs[].results | length' codeql-results-go.sarif

# Details
jq -r '.runs[].results[] | "\(.level): \(.message.text) (\(.locations[0].physicalLocation.artifactLocation.uri):\(.locations[0].physicalLocation.region.startLine))"' codeql-results-go.sarif

Method 3: GitHub Security Tab

• CI automatically uploads results to: https://github.com/YourOrg/Charon/security/code-scanning

Understanding Query Suites

Charon uses the security-and-quality suite (GitHub Actions default):

Suite	Go Queries	JS Queries	Use Case
security-extended	39	106	Security-only, faster
security-and-quality	61	204	Security + quality, comprehensive (CI default)

⚠️ Important: Local scans MUST use security-and-quality to match CI behavior.

Severity Levels

• 🔴 Error (High/Critical): Must fix before merge - CI will fail
• 🟡 Warning (Medium): Should fix - CI continues
• 🔵 Note (Low/Info): Consider fixing - CI continues

Common Issues & Fixes

Issue: "CWE-918: Server-Side Request Forgery (SSRF)"

Location: backend/internal/api/handlers/url_validator.go

Fix:

// BAD: Unrestricted URL
resp, err := http.Get(userProvidedURL)

// GOOD: Validate against allowlist
if !isAllowedHost(userProvidedURL) {
    return ErrSSRFAttempt
}
resp, err := http.Get(userProvidedURL)

Reference: docs/security/ssrf-protection.md

Issue: "CWE-079: Cross-Site Scripting (XSS)"

Location: frontend/src/components/...

Fix:

// BAD: Unsafe HTML rendering
element.innerHTML = userInput;

// GOOD: Safe text content
element.textContent = userInput;

// GOOD: Sanitized HTML (if HTML is required)
import DOMPurify from 'dompurify';
element.innerHTML = DOMPurify.sanitize(userInput);

Issue: "CWE-089: SQL Injection"

Fix: Use parameterized queries (GORM handles this automatically)

// BAD: String concatenation
db.Raw("SELECT * FROM users WHERE name = '" + userName + "'")

// GOOD: Parameterized query
db.Where("name = ?", userName).Find(&users)

CI/CD Integration

When CodeQL Runs

• Push: Every commit to main, development, feature/*
• Pull Request: Every PR to main, development
• Schedule: Weekly scan on Monday at 3 AM UTC

CI Behavior

✅ Allowed to merge:

• No findings
• Only warnings/notes
• Forked PRs (security scanning skipped for permission reasons)

❌ Blocked from merge:

• Any error-level (high/critical) findings
• CodeQL analysis failure

Viewing CI Results

1. PR Checks: See "CodeQL analysis (go)" and "CodeQL analysis (javascript-typescript)" checks
2. Security Tab: Navigate to repo → Security → Code scanning alerts
3. Workflow Summary: Click on failed check → View job summary

Troubleshooting

"CodeQL passes locally but fails in CI"

Cause: Using wrong query suite locally

Fix: Ensure tasks use security-and-quality:

codeql database analyze DB_PATH \
  codeql/LANGUAGE-queries:codeql-suites/LANGUAGE-security-and-quality.qls \
  ...

"SARIF file not found"

Cause: Database creation or analysis failed

Fix:

1. Check terminal output for errors
2. Ensure CodeQL is installed: codeql version
3. Verify source-root exists: ls backend/ or ls frontend/

"Too many findings to fix"

Strategy:

1. Fix all error level first (CI blockers)
2. Create issues for warning level (non-blocking)
3. Document note level for future consideration

Suppress false positives:

// codeql[go/sql-injection] - Safe: input is validated by ACL
db.Raw(query).Scan(&results)

Performance Tips

• Incremental Scans: CodeQL caches databases, second run is faster
• Parallel Execution: Use --threads=0 for auto-detection
• CI Only: Run full scans in CI, quick checks locally

References

• CodeQL Documentation
• OWASP Top 10
• CWE Database
• Charon Security Policy