Initial commit - 611 cybersecurity skills across all subdomains

2026-06-10 21:24:56 +03:00 · 2026-02-25 10:47:44 +01:00
commit 22a7ab1462
1765 changed files with 280648 additions and 0 deletions
@@ -0,0 +1,188 @@
+---
+name: implementing-github-advanced-security-for-code-scanning
+description: Configure GitHub Advanced Security with CodeQL to perform automated static analysis and vulnerability detection across repositories at enterprise scale.
+domain: cybersecurity
+subdomain: devsecops
+tags: [github-advanced-security, codeql, sast, code-scanning, supply-chain-security, devops-security, shift-left]
+version: "1.0"
+author: mahipal
+license: MIT
+---
+
+# Implementing GitHub Advanced Security for Code Scanning
+
+## Overview
+
+GitHub Advanced Security (GHAS) integrates CodeQL-powered static application security testing directly into the GitHub development workflow. CodeQL treats code as data, enabling semantic analysis that identifies security vulnerabilities such as SQL injection, cross-site scripting, buffer overflows, and authentication flaws with significantly fewer false positives than traditional pattern-matching scanners. GHAS encompasses code scanning, secret scanning, dependency review, and Dependabot alerts to provide a comprehensive security posture for repositories.
+
+## Prerequisites
+
+- GitHub Enterprise Cloud or GitHub Enterprise Server 3.0+ with GHAS license
+- Repository admin or organization owner permissions
+- Familiarity with GitHub Actions workflow syntax (YAML)
+- Supported languages: C/C++, C#, Go, Java/Kotlin, JavaScript/TypeScript, Python, Ruby, Swift
+
+## Core Concepts
+
+### CodeQL Analysis Engine
+
+CodeQL compiles source code into a queryable database, then executes security-focused queries against that database. The query suites ship with hundreds of checks mapped to CWE identifiers and cover OWASP Top 10, SANS Top 25, and language-specific vulnerability patterns. Custom queries can be authored using the CodeQL query language (QL) to detect organization-specific anti-patterns.
+
+### Default Setup vs. Advanced Setup
+
+**Default Setup** enables code scanning with a single click from the repository's Code Security settings. GitHub automatically determines the languages present, selects appropriate query suites, and configures scanning triggers. This approach requires no workflow file and is ideal for rapid onboarding.
+
+**Advanced Setup** generates a `.github/workflows/codeql.yml` workflow file that can be customized. Teams control scheduling, language matrices, build commands for compiled languages, additional query packs, and integration with third-party SARIF producers. Advanced setup is required when custom build steps, monorepo configurations, or private query packs are needed.
+
+### Organization-Wide Rollout
+
+For enterprises managing hundreds of repositories, GHAS supports configuring code scanning at scale using the organization-level security overview. Administrators can enable default setup across all eligible repositories, define custom security configurations, and monitor adoption through the security coverage dashboard.
+
+## Implementation Steps
+
+### Step 1 --- Enable GHAS on the Organization
+
+1. Navigate to Organization Settings > Code security and analysis
+2. Enable GitHub Advanced Security for all repositories or selected repositories
+3. Confirm license seat allocation (GHAS is billed per active committer)
+
+### Step 2 --- Configure Default Setup for Quick Wins
+
+1. Go to Repository Settings > Code security > Code scanning
+2. Click "Set up" in the CodeQL analysis row and select "Default"
+3. Review the auto-detected languages and query suite (default or extended)
+4. Click "Enable CodeQL" to activate scanning on push and pull request events
+
+### Step 3 --- Advanced Setup with Custom Workflow
+
+Create `.github/workflows/codeql-analysis.yml`:
+
+```yaml
+name: "CodeQL Analysis"
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '30 2 * * 1'  # Weekly Monday 2:30 AM UTC
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      contents: read
+      actions: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: ['javascript-typescript', 'python', 'java-kotlin']
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
+          queries: +security-extended,security-and-quality
+          # For compiled languages, add build commands below
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v3
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:${{ matrix.language }}"
+```
+
+### Step 4 --- Custom Query Packs
+
+Install organization-specific query packs by referencing them in the workflow:
+
+```yaml
+- name: Initialize CodeQL
+  uses: github/codeql-action/init@v3
+  with:
+    languages: java-kotlin
+    packs: |
+      my-org/java-custom-queries@1.0.0
+      codeql/java-queries:cwe/cwe-089
+```
+
+### Step 5 --- Configure Branch Protection Rules
+
+1. Navigate to Repository Settings > Branches > Branch protection rules
+2. Enable "Require status checks to pass" and add the CodeQL analysis check
+3. Enable "Require code scanning results" and set severity thresholds (e.g., block on High/Critical)
+
+### Step 6 --- Secret Scanning and Push Protection
+
+1. Enable secret scanning from Code security settings
+2. Activate push protection to block commits containing detected secrets
+3. Configure custom patterns for organization-specific secrets (API keys, internal tokens)
+
+### Step 7 --- Dependency Review and Dependabot
+
+1. Enable Dependabot alerts and security updates
+2. Configure `.github/dependabot.yml` for automated dependency version updates
+3. Enable dependency review enforcement on pull requests to block PRs that introduce known vulnerable dependencies
+
+## Query Suite Reference
+
+| Suite | Description | Use Case |
+|-------|-------------|----------|
+| `default` | High-confidence security queries | Production scanning with minimal false positives |
+| `security-extended` | Broader security queries including lower-severity findings | Comprehensive security coverage |
+| `security-and-quality` | Security plus code quality queries | Teams wanting both security and maintainability checks |
+| Custom packs | Organization-authored queries | Detecting internal anti-patterns and compliance violations |
+
+## Integration with Security Workflows
+
+### SARIF Upload from Third-Party Tools
+
+GHAS accepts SARIF (Static Analysis Results Interchange Format) uploads from external tools:
+
+```yaml
+- name: Upload SARIF
+  uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: results.sarif
+    category: "semgrep"
+```
+
+### Security Overview Dashboard
+
+The organization-level security overview provides:
+- Risk view showing repositories with open alerts by severity
+- Coverage view showing GHAS feature enablement across repositories
+- Alert trends over time for tracking remediation progress
+- Filter by team, language, and alert type for targeted review
+
+## Monitoring and Metrics
+
+- Track mean time to remediate (MTTR) for code scanning alerts
+- Monitor false positive rates and tune query configurations accordingly
+- Review alert dismissal reasons to identify areas for developer training
+- Use the API (`/repos/{owner}/{repo}/code-scanning/alerts`) for custom reporting dashboards
+
+## Common Pitfalls
+
+1. **Compiled language build failures** --- CodeQL requires successful compilation for C/C++, Java, C#, Go, and Swift; ensure build dependencies are available in the Actions runner
+2. **Ignoring scheduled scans** --- Push/PR scanning misses vulnerabilities in dependencies; weekly scheduled scans catch newly disclosed CVEs in existing code
+3. **Over-alerting with security-and-quality** --- Start with `default` suite and expand gradually to avoid developer alert fatigue
+4. **Missing GHAS license seats** --- Only active committers to GHAS-enabled repositories consume license seats; plan capacity accordingly
+
+## References
+
+- [GitHub Code Scanning Documentation](https://docs.github.com/en/code-security/code-scanning)
+- [CodeQL Documentation](https://codeql.github.com/docs/)
+- [CodeQL Query Repository](https://github.com/github/codeql)
+- [SARIF Specification](https://sarifweb.azurewebsites.net/)
+- [GitHub Security Overview](https://docs.github.com/en/code-security/security-overview/about-security-overview)
@@ -0,0 +1,60 @@
+# GHAS Code Scanning Implementation Template
+
+## Organization Security Configuration
+
+| Setting | Value | Notes |
+|---------|-------|-------|
+| Organization | `_______________` | |
+| GHAS License Seats | `_______________` | Active committers |
+| Default Query Suite | [ ] default [ ] security-extended [ ] security-and-quality | |
+| Branch Protection Enabled | [ ] Yes [ ] No | |
+| Secret Scanning Enabled | [ ] Yes [ ] No | |
+| Push Protection Enabled | [ ] Yes [ ] No | |
+| Dependabot Enabled | [ ] Yes [ ] No | |
+
+## Repository Enablement Tracker
+
+| Repository | Languages | Setup Type | Scanning Active | Open Alerts | Date Enabled |
+|------------|-----------|------------|-----------------|-------------|--------------|
+| | | [ ] Default [ ] Advanced | [ ] Yes [ ] No | | |
+| | | [ ] Default [ ] Advanced | [ ] Yes [ ] No | | |
+| | | [ ] Default [ ] Advanced | [ ] Yes [ ] No | | |
+
+## Custom Query Pack Registry
+
+| Pack Name | Version | Description | Target Languages |
+|-----------|---------|-------------|------------------|
+| | | | |
+
+## Alert Severity Gate Configuration
+
+| Environment | Block on Critical | Block on High | Block on Medium | Block on Low |
+|-------------|-------------------|---------------|-----------------|--------------|
+| Production (main) | [x] Yes | [x] Yes | [ ] Yes | [ ] No |
+| Staging (develop) | [x] Yes | [ ] Yes | [ ] No | [ ] No |
+| Feature branches | [x] Yes | [ ] Yes | [ ] No | [ ] No |
+
+## Secret Scanning Custom Patterns
+
+| Pattern Name | Regex | Description | Alert Enabled | Push Protection |
+|--------------|-------|-------------|---------------|-----------------|
+| | | | [ ] Yes [ ] No | [ ] Yes [ ] No |
+
+## Weekly Security Review Checklist
+
+- [ ] Review new critical and high severity alerts
+- [ ] Check alert dismissal reasons for quality
+- [ ] Verify new repositories have scanning enabled
+- [ ] Review Dependabot alerts and merge security updates
+- [ ] Check secret scanning alerts for exposed credentials
+- [ ] Update security overview dashboard metrics
+- [ ] Review MTTR trends and identify bottlenecks
+
+## Escalation Matrix
+
+| Alert Severity | Response SLA | Escalation Contact | Action Required |
+|----------------|-------------|--------------------|-----------------|
+| Critical | 24 hours | Security Lead | Immediate remediation, potential incident |
+| High | 72 hours | Team Lead | Prioritize in current sprint |
+| Medium | 2 weeks | Developer | Schedule for next sprint |
+| Low | 30 days | Developer | Add to backlog |
@@ -0,0 +1,40 @@
+# Standards and Frameworks Reference
+
+## OWASP Top 10 (2021) Coverage by CodeQL
+
+| OWASP Category | CodeQL CWE Coverage | Query Suite |
+|----------------|---------------------|-------------|
+| A01 Broken Access Control | CWE-22, CWE-284, CWE-639 | security-extended |
+| A02 Cryptographic Failures | CWE-259, CWE-327, CWE-328 | security-extended |
+| A03 Injection | CWE-77, CWE-78, CWE-79, CWE-89 | default |
+| A04 Insecure Design | CWE-209, CWE-256, CWE-501 | security-and-quality |
+| A05 Security Misconfiguration | CWE-16, CWE-611 | security-extended |
+| A06 Vulnerable Components | Dependency Review / Dependabot | N/A (separate feature) |
+| A07 Auth Failures | CWE-287, CWE-798 | default |
+| A08 Data Integrity Failures | CWE-502, CWE-829 | security-extended |
+| A09 Logging Failures | CWE-117, CWE-778 | security-and-quality |
+| A10 SSRF | CWE-918 | default |
+
+## NIST SP 800-218 (SSDF) Alignment
+
+- **PO.3**: Define security requirements --- CodeQL enforces security policies through query suites
+- **PW.4**: Reuse existing, well-secured software --- Dependabot ensures dependencies are patched
+- **PW.7**: Review and test code for vulnerabilities --- Automated code scanning on every PR
+- **PW.8**: Test executable code --- SARIF integration enables combining SAST with DAST results
+- **RV.1**: Identify and confirm vulnerabilities --- Security overview tracks alerts across the organization
+
+## CIS Software Supply Chain Security Guide
+
+- **SCS-1**: Source code management security --- Branch protection rules, required reviewers
+- **SCS-2**: Build pipelines --- CodeQL runs in GitHub Actions with pinned action versions
+- **SCS-5**: Artifact management --- Dependency review prevents vulnerable packages from merging
+
+## ISO 27001 Control Mapping
+
+| ISO 27001 Control | GHAS Feature |
+|--------------------|--------------|
+| A.8.25 Secure development lifecycle | CodeQL in CI/CD pipeline |
+| A.8.26 Application security requirements | Custom query packs for org standards |
+| A.8.28 Secure coding | Real-time scanning on pull requests |
+| A.8.29 Security testing in dev and acceptance | Required status checks with severity gates |
+| A.8.31 Separation of environments | Branch protection and deployment rules |
@@ -0,0 +1,104 @@
+# GHAS Implementation Workflows
+
+## Workflow 1: Organization-Wide Enablement
+
+```
+1. Audit current repository inventory
+   - List all repositories in the organization
+   - Identify languages and build systems in use
+   - Estimate active committer count for licensing
+   |
+2. Pilot phase (2-4 weeks)
+   - Enable GHAS on 5-10 representative repositories
+   - Use default setup for initial scanning
+   - Collect baseline alert counts and false positive rates
+   |
+3. Triage pilot results
+   - Review alerts by severity (Critical, High, Medium, Low)
+   - Dismiss confirmed false positives with documented reasons
+   - Create remediation issues for confirmed vulnerabilities
+   |
+4. Tune configuration
+   - Adjust query suites based on false positive feedback
+   - Write custom queries for organization-specific patterns
+   - Configure alert dismissal policies
+   |
+5. Broad rollout
+   - Enable default setup across remaining repositories
+   - Configure organization-level security configurations
+   - Set branch protection rules requiring code scanning checks
+   |
+6. Continuous monitoring
+   - Review security overview dashboard weekly
+   - Track MTTR for code scanning alerts
+   - Report metrics to security leadership monthly
+```
+
+## Workflow 2: Pull Request Security Gate
+
+```
+Developer pushes code to feature branch
+           |
+   PR is created targeting main
+           |
+   CodeQL analysis triggers automatically
+           |
+   Dependency review checks for vulnerable dependencies
+           |
+   Secret scanning checks for hardcoded credentials
+           |
+   Results posted as PR check and inline annotations
+           |
+   [Pass] All checks pass --> PR is eligible for merge
+   [Fail] Critical/High findings --> PR is blocked
+           |
+   Developer reviews findings and applies fixes
+           |
+   Re-push triggers re-analysis
+           |
+   Merge after all checks pass and reviewer approval
+```
+
+## Workflow 3: Custom CodeQL Query Development
+
+```
+1. Identify recurring vulnerability pattern not caught by default queries
+   |
+2. Set up CodeQL development environment
+   - Install CodeQL CLI
+   - Clone CodeQL standard library repository
+   - Create workspace with target codebase database
+   |
+3. Author the query in QL language
+   - Define source, sink, and taint-tracking configuration
+   - Add metadata (@name, @description, @kind, @problem.severity, @security-severity, @precision, @id, @tags)
+   |
+4. Test the query
+   - Create test cases with expected results
+   - Run `codeql test run` against test database
+   - Validate precision and recall
+   |
+5. Package the query
+   - Create qlpack.yml with version and dependencies
+   - Publish to GitHub Container Registry or internal package registry
+   |
+6. Deploy to scanning workflow
+   - Reference the query pack in codeql-action/init step
+   - Monitor results for the new query across repositories
+```
+
+## Workflow 4: SARIF Integration with External Tools
+
+```
+External SAST/DAST tool runs scan
+           |
+   Tool outputs results in SARIF 2.1.0 format
+           |
+   GitHub Actions uploads SARIF via codeql-action/upload-sarif
+           |
+   Results appear in Security tab alongside CodeQL findings
+           |
+   Unified triage workflow across all scanning tools
+           |
+   Alert deduplication based on location and rule ID
+```
@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""
+GitHub Advanced Security Code Scanning Alert Management
+
+Uses the GitHub REST API to query, triage, and report on CodeQL
+code scanning alerts across an organization's repositories.
+"""
+
+import json
+import os
+import sys
+import urllib.request
+import urllib.error
+from datetime import datetime, timedelta
+from collections import defaultdict
+
+
+def get_github_headers(token: str) -> dict:
+    return {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+
+
+def github_api_get(url: str, token: str) -> list | dict:
+    headers = get_github_headers(token)
+    results = []
+    page = 1
+    while True:
+        paginated_url = f"{url}{'&' if '?' in url else '?'}per_page=100&page={page}"
+        req = urllib.request.Request(paginated_url, headers=headers)
+        try:
+            with urllib.request.urlopen(req) as resp:
+                data = json.loads(resp.read().decode())
+                if isinstance(data, list):
+                    if not data:
+                        break
+                    results.extend(data)
+                    page += 1
+                else:
+                    return data
+        except urllib.error.HTTPError as e:
+            print(f"HTTP {e.code} for {paginated_url}: {e.read().decode()}")
+            break
+    return results
+
+
+def list_org_repos(org: str, token: str) -> list:
+    url = f"https://api.github.com/orgs/{org}/repos?type=all"
+    repos = github_api_get(url, token)
+    return [r["full_name"] for r in repos if isinstance(r, dict)]
+
+
+def get_code_scanning_alerts(repo: str, token: str, state: str = "open") -> list:
+    url = f"https://api.github.com/repos/{repo}/code-scanning/alerts?state={state}"
+    return github_api_get(url, token)
+
+
+def categorize_alerts(alerts: list) -> dict:
+    categories = defaultdict(lambda: defaultdict(int))
+    for alert in alerts:
+        rule = alert.get("rule", {})
+        severity = rule.get("security_severity_level", "unknown")
+        cwe_tags = [t for t in rule.get("tags", []) if t.startswith("cwe-")]
+        tool_name = alert.get("tool", {}).get("name", "unknown")
+        categories["by_severity"][severity] += 1
+        categories["by_tool"][tool_name] += 1
+        for cwe in cwe_tags:
+            categories["by_cwe"][cwe] += 1
+    return dict(categories)
+
+
+def calculate_mttr(alerts: list) -> dict:
+    resolved = [a for a in alerts if a.get("state") == "fixed"]
+    if not resolved:
+        return {"total_resolved": 0, "avg_mttr_hours": None}
+
+    durations = []
+    for alert in resolved:
+        created = datetime.fromisoformat(alert["created_at"].replace("Z", "+00:00"))
+        fixed = datetime.fromisoformat(
+            alert.get("fixed_at", alert.get("dismissed_at", "")).replace("Z", "+00:00")
+        )
+        durations.append((fixed - created).total_seconds() / 3600)
+
+    return {
+        "total_resolved": len(resolved),
+        "avg_mttr_hours": round(sum(durations) / len(durations), 1),
+        "min_mttr_hours": round(min(durations), 1),
+        "max_mttr_hours": round(max(durations), 1),
+    }
+
+
+def generate_org_report(org: str, token: str) -> dict:
+    repos = list_org_repos(org, token)
+    report = {
+        "organization": org,
+        "generated_at": datetime.utcnow().isoformat() + "Z",
+        "total_repositories": len(repos),
+        "repositories_with_scanning": 0,
+        "total_open_alerts": 0,
+        "severity_summary": defaultdict(int),
+        "top_cwes": defaultdict(int),
+        "repo_details": [],
+    }
+
+    for repo in repos:
+        alerts = get_code_scanning_alerts(repo, token, state="open")
+        if not alerts:
+            continue
+
+        report["repositories_with_scanning"] += 1
+        report["total_open_alerts"] += len(alerts)
+        categories = categorize_alerts(alerts)
+
+        for sev, count in categories.get("by_severity", {}).items():
+            report["severity_summary"][sev] += count
+        for cwe, count in categories.get("by_cwe", {}).items():
+            report["top_cwes"][cwe] += count
+
+        closed_alerts = get_code_scanning_alerts(repo, token, state="fixed")
+        mttr = calculate_mttr(closed_alerts)
+
+        report["repo_details"].append(
+            {
+                "repository": repo,
+                "open_alerts": len(alerts),
+                "severity_breakdown": dict(categories.get("by_severity", {})),
+                "mttr": mttr,
+            }
+        )
+
+    report["severity_summary"] = dict(report["severity_summary"])
+    top_cwes_sorted = sorted(report["top_cwes"].items(), key=lambda x: x[1], reverse=True)[:10]
+    report["top_cwes"] = dict(top_cwes_sorted)
+    return report
+
+
+def print_report(report: dict) -> None:
+    print(f"\n{'='*60}")
+    print(f"GHAS Code Scanning Report: {report['organization']}")
+    print(f"Generated: {report['generated_at']}")
+    print(f"{'='*60}")
+    print(f"Total repositories: {report['total_repositories']}")
+    print(f"Repositories with scanning enabled: {report['repositories_with_scanning']}")
+    coverage = (
+        report["repositories_with_scanning"] / report["total_repositories"] * 100
+        if report["total_repositories"] > 0
+        else 0
+    )
+    print(f"Coverage: {coverage:.1f}%")
+    print(f"Total open alerts: {report['total_open_alerts']}")
+    print(f"\nSeverity Summary:")
+    for sev in ["critical", "high", "medium", "low", "unknown"]:
+        count = report["severity_summary"].get(sev, 0)
+        if count > 0:
+            print(f"  {sev.upper():12s}: {count}")
+    print(f"\nTop CWEs:")
+    for cwe, count in report.get("top_cwes", {}).items():
+        print(f"  {cwe:15s}: {count}")
+    print(f"\nRepository Details:")
+    for repo in sorted(report["repo_details"], key=lambda r: r["open_alerts"], reverse=True):
+        mttr_str = (
+            f"{repo['mttr']['avg_mttr_hours']}h" if repo["mttr"]["avg_mttr_hours"] else "N/A"
+        )
+        print(f"  {repo['repository']:40s} | Open: {repo['open_alerts']:4d} | Avg MTTR: {mttr_str}")
+
+
+def main():
+    token = os.environ.get("GITHUB_TOKEN")
+    if not token:
+        print("Error: GITHUB_TOKEN environment variable is required")
+        sys.exit(1)
+
+    org = os.environ.get("GITHUB_ORG")
+    if not org:
+        print("Error: GITHUB_ORG environment variable is required")
+        sys.exit(1)
+
+    print(f"Fetching code scanning data for organization: {org}")
+    report = generate_org_report(org, token)
+    print_report(report)
+
+    output_file = f"ghas_report_{org}_{datetime.utcnow().strftime('%Y%m%d')}.json"
+    with open(output_file, "w") as f:
+        json.dump(report, f, indent=2, default=str)
+    print(f"\nDetailed report saved to: {output_file}")
+
+
+if __name__ == "__main__":
+    main()