Security Code Scanner Monorepo

Unified security code scanning system with CodeQL and Semgrep

🏗️ Architecture

This monorepo provides a reusable security scanning workflow with automatic language detection and parallel execution:

• .github/workflows/security-scan.yml - Main reusable workflow (orchestrator)
• .github/ - Workspace package for workflow versioning (@metamask/action-code-scanner-github)
• packages/language-detector/ - Detects languages and creates scan matrix
• packages/codeql-action/ - Custom CodeQL analysis with repo-specific configs
• packages/semgrep-action/ - Semgrep pattern-based scanner

🚀 Quick Start

Using the Scanner (Recommended)

Add to your repository's .github/workflows/security.yml:

name: 'Security Scan'on: [push, pull_request]jobs:
security-scan:
uses: MetaMask/action-security-code-scanner/.github/workflows/security-scan.yml@v2with:
scanner-ref: v2permissions:
actions: readcontents: readsecurity-events: write

The workflow will:

1. Auto-detect languages in your repository
2. Load repo-specific config from repo-configs/ (or use defaults)
3. Run CodeQL and Semgrep scans in parallel
4. Upload SARIF results to GitHub Security tab

Custom Configuration

Option 1: File-based config (recommended)

Create repo-configs/<your-repo-name>.js in this monorepo:

constconfig={pathsIgnored: ['test','docs'],rulesExcluded: ['js/log-injection'],languages_config: [{language: 'java-kotlin',build_mode: 'manual',build_command: './gradlew build',version: '21',distribution: 'temurin',},],queries: [{name: 'Security queries',uses: './query-suites/base.qls'},{name: 'Custom queries',uses: './custom-queries/query-suites/custom-queries.qls',},],};exportdefaultconfig;

Option 2: Workflow input (overrides file config)

jobs:
security-scan:
uses: metamask/security-codescanner-monorepo/.github/workflows/security-scan.yml@mainwith:
repo: ${{ github.repository }}languages_config: | [ { "language": "java-kotlin", "build_mode": "manual", "build_command": "./gradlew build", "version": "21" } ]paths_ignored: 'test,docs'rules_excluded: 'js/log-injection,py/sql-injection'

Testing from Dev Branch

When testing changes to the security scanner itself from a dev branch, you must explicitly pass the ref input:

jobs:
security-scan:
uses: metamask/security-codescanner-monorepo/.github/workflows/security-scan.yml@dev-branchwith:
repo: ${{ github.repository }}ref: dev-branch # Must explicitly pass the branch name

Note: The @branch in the uses: statement only affects which workflow file is used. The ref input ensures all internal monorepo checkouts use the same branch.

📦 Package Structure

security-scanner-monorepo/
├── .github/ # Workflow workspace package
│ ├── package.json
│ └── workflows/
│ └── security-scan.yml # Main reusable workflow
├── packages/
│ ├── language-detector/ # Language detection & matrix creation
│ ├── codeql-action/ # CodeQL scanner
│ │ ├── repo-configs/ # Repository-specific configs
│ │ ├── query-suites/ # CodeQL query suites
│ │ ├── scripts/ # Config generation scripts
│ │ └── src/ # Shared utilities
│ └── semgrep-action/ # Semgrep scanner
└── SECURITY.md # Security model documentation

🔧 Development

Setup

# Install dependencies
yarn install
# Run linting
yarn lint
# Fix formatting
yarn lint:fix

Testing

# Test language detector
yarn workspace @metamask/language-detector test# Test with integration tests
yarn workspace @metamask/language-detector test:integration

Workspace Commands

# Run command in specific package
yarn workspace @metamask/language-detector <command># Run command in all packages
yarn workspaces foreach run <command>

📚 Configuration Schema

Repo Config File (repo-configs/<repo-name>.js)

{// Paths to ignore during scanpathsIgnored: ['test','vendor'],// Rule IDs to excluderulesExcluded: ['js/log-injection'],// Per-language configurationlanguages_config: [{language: 'java-kotlin',// CodeQL languageignore: false,// Skip this language (optional)build_mode: 'manual',// 'none', 'autobuild', or 'manual'build_command: './gradlew build',version: '21',// Language/runtime versiondistribution: 'temurin'// Distribution (Java/Node.js)}],// CodeQL query suitesqueries: [{name: 'Base queries',uses: './query-suites/base.qls'}]}

Supported Languages

CodeQL:

• JavaScript/TypeScript → javascript-typescript
• Python → python
• Java/Kotlin → java-kotlin
• Go → go
• C/C++ → cpp
• C# → csharp
• Ruby → ruby

Semgrep: All languages (language-agnostic pattern matching)

🎯 Key Features

✅ Automatic Language Detection

• Detects languages via GitHub API
• Maps to appropriate scanners
• Configurable per-repository

✅ Optimized Execution

• Parallel scanning per language
• Matrix-based job strategy
• Fail-fast for ignored languages

✅ Flexible Configuration

• File-based configs (single source of truth)
• Workflow input overrides
• Per-language build settings

✅ Security First

• Minimal token permissions (contents: read, security-events: write)
• Input validation and sanitization
• See SECURITY.md for threat model

🔍 Troubleshooting

Language not detected

• Check GitHub's language detection (repo insights → languages)
• Ensure language is in LANGUAGE_MAPPING in language-detector/src/job-configurator.js
• Add manual languages_config in workflow input

Build failures

• Verify build_command in repo config
• Check if correct version and distribution are specified
• Review CodeQL build logs in Actions

Config not loading

• Repo config filename must match repo name: owner/repo → repo.js
• Ensure config file exports with export default config
• Check config-loader logs in workflow output

Permissions errors

• Add required permissions to calling workflow:

  permissions:
  actions: readcontents: readsecurity-events: write

📄 License

ISC

🤝 Contributing

See SECURITY.md for security model and REVIEW_TRACKING.md for current development status.

Package Documentation

• CodeQL Action README
• Language Detector README
• Semgrep Action README