codeql quick setup

CodeQL Quick Setup Guide

What is CodeQL?

CodeQL is GitHub's code analysis engine that identifies vulnerabilities and code quality issues in your repository. It scans for security flaws, suspicious patterns, and best practice violations.

Prerequisites

Your repository must have:

• GitHub Advanced Security enabled (Enterprise, Pro, or Team plan)
• Public repository OR private with Advanced Security
• .github/workflows/ directory
• GitHub Actions enabled

Current Setup

Your project now has CodeQL integrated into the unified-ci.yml workflow:

What Gets Scanned

• ✅ JavaScript/TypeScript code
• ✅ Frontend code (/frontend)
• ✅ Backend code (/backend)
• ✅ Scripts and utilities
• ✅ VSCode extension code

What Gets Excluded

• ❌ node_modules/ directories
• ❌ Build artifacts (/dist, /build)
• ❌ Test files and coverage
• ❌ Minified files
• ❌ Third-party code

How to Enable/Configure

1. Verify Permissions (Already Set)

The workflow includes required permissions:

permissions:
  security-events: write  # Allows CodeQL to report results
  contents: read          # Allows reading source code
  actions: read           # Allows reading GitHub Actions

2. Check Repository Settings

Go to: Settings → Code security and analysis

Ensure enabled:

• ✅ Dependency graph (if applicable)
• ✅ Code scanning - CodeQL (or custom)
• ✅ Secret scanning (premium feature)
• ✅ Private vulnerability reporting (premium feature)

3. Workflow Execution

CodeQL runs automatically on:

• ✅ Push to main branch
• ✅ Pull requests to main branch
• ✅ Releases published
• ✅ Scheduled runs (configurable)

4. View Results

After workflow runs, results appear in:

Repository Dashboard

Security tab → Code scanning alerts

Pull Request Checks

• Inline annotations on PR
• Summary in checks section
• Allows dismissing or fixing

GitHub CLI

gh code-scanning view --repo OWNER/REPO

Configuration Files

.github/codeql-config.yml

Main configuration for CodeQL behavior:

• Paths to scan/ignore
• Languages to analyze
• Query sets to use
• Performance tuning

.github/workflows/unified-ci.yml

Workflow definition:

• When CodeQL runs
• What languages to scan
• How to handle results
• Integration with other checks

Interpreting Results

Alert Severity

• 🔴 Error: Critical security vulnerability
• 🟡 Warning: Potential issue to investigate
• 🟢 Note: Informational, good practice

Alert Types

Security Issues

• SQL injection prevention
• Cross-site scripting (XSS)
• Command injection
• Sensitive data exposure
• Authentication bypass

Code Quality

• Dead code
• Unreachable code
• Resource leaks
• Type mismatches
• Potential null pointer exceptions

Fixing Issues

Steps to Fix

1. Review the Alert

   • Click alert in GitHub
   • Read description and CWE reference
   • View code path leading to issue

2. Understand the Problem

   • Check affected code
   • Review usage patterns
   • Check data flow

3. Implement Fix

   • Use suggested remediation
   • Apply security best practices
   • Test thoroughly

4. Verify Fix

   • Re-run CodeQL
   • Confirm alert is resolved
   • Close/dismiss alert if needed

Common Fixes

SQL Injection

// ❌ Bad
const query = `SELECT * FROM users WHERE id = ${userId}`;

// ✅ Good
const query = `SELECT * FROM users WHERE id = ?`;
db.query(query, [userId]);

XSS Prevention

// ❌ Bad
element.innerHTML = userInput;

// ✅ Good
element.textContent = userInput;
// or use DOMPurify library

Command Injection

// ❌ Bad
exec(`rm -rf ${path}`);

// ✅ Good
fs.rmSync(path, { recursive: true });

Suppressing False Positives

Mark as Dismissed (GitHub UI)

1. Open alert
2. Click "Dismiss"
3. Select reason (false positive, won't fix, etc.)
4. Add comment (optional)

Code-Level Suppression

JavaScript/TypeScript:

// lgtm[js/sql-injection]
const query = `SELECT * FROM table WHERE id = ${id}`;

Scheduling CodeQL

Run on Schedule

To add scheduled runs, update workflow:

on:
  schedule:
    - cron: '30 2 * * 0'  # Weekly Sunday 2:30 AM UTC

Customize Build

For interpreted languages like JavaScript:

build-mode: none  # No build step needed

For compiled languages:

build-mode: autobuild  # Or manual with steps

Troubleshooting

Issue: "Bad credentials"

Solution: Check repository has Advanced Security enabled and workflow has security-events: write permission.

Issue: No results shown

Solution:

1. Check workflow ran successfully (Actions tab)
2. Verify repository settings allow code scanning
3. Wait for analysis to complete (can take several minutes)

Issue: Too many false positives

Solution:

1. Review alert severity levels
2. Dismiss or fix high-confidence issues first
3. Adjust query configuration in codeql-config.yml

Issue: Workflow running slow

Solution:

1. Reduce number of queries (use 'security-and-quality' instead of 'security-extended')
2. Exclude large directories
3. Increase runner resources (change runs-on)

Advanced Configuration

Custom Queries

Create .github/codeql/custom-queries.ql files for organization-specific rules.

Multi-Language Analysis

Add to workflow:

strategy:
  matrix:
    language: ['javascript-typescript', 'python', 'go']

Severity Thresholds

Block PRs on high-severity findings by adding branch protection rules.

Best Practices

1. Regular Reviews: Check alerts weekly
2. Fix Immediately: Don't accumulate technical debt
3. Team Education: Share alerts with team
4. Document Decisions: Comment on dismissed alerts
5. Track Trends: Monitor alert counts over time
6. Update Configuration: Refine rules as you learn patterns

Resources

• 📖 CodeQL Documentation
• 🔗 GitHub Code Scanning Docs
• 💬 CodeQL Community Forum
• 📝 CWE/OWASP References

Support

For issues:

1. Check logs in GitHub Actions
2. Review this troubleshooting guide
3. Open GitHub issue in CodeQL repository
4. Contact GitHub Support (Enterprise)