diff --git a/Dockerfile.example b/Dockerfile.example new file mode 100644 index 0000000..e38074e --- /dev/null +++ b/Dockerfile.example @@ -0,0 +1,33 @@ +FROM ubuntu +LABEL description="Security & Quality CodeQL Container Build for Cool Applications" +SHELL ["/bin/bash", "-c"] +ENV TZ=America/New_York + +# create directories +RUN mkdir /tools + +# setup tools +RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone +RUN DEBIAN_FRONTEND="noninteractive" apt-get update && apt-get install -y golang zip wget +RUN wget -q https://github.com/github/codeql-action/releases/download/codeql-bundle-20211005/codeql-bundle-linux64.tar.gz +RUN tar xzf /codeql-bundle-linux64.tar.gz -C tools + +# copy source +COPY . /usr/src/myapp + +# set working directory +WORKDIR /usr/src/myapp + +# example repo used: https://github.com/ghas-bootcamp/ghas-bootcamp + +# codeql create +RUN /tools/codeql/codeql database create db --language=javascript, java --db-cluster --no-run-unnecessary-builds -vvvv + +# codeql analyze with default queries +RUN /tools/codeql/codeql database analyze codeql-database/go go-code-scanning.qls --format=sarif-latest --output=codeql-go-results.sarif --sarif-category=goiscool +RUN /tools/codeql/codeql database analyze db javascript-code-scanning.qls --format=sarif-latest --output=codeql-javascript-results.sarif --sarif-category=javascriptiscool + +# upload results +# remember to get the MERGE commit for a PR +RUN /tools/codeql/codeql github upload-results --github-url= --repository=oreos/miniature-invention --ref=refs/pull/1/merge --commit=778337f84a5abe2cda468c7abf6038b8a193cea2 --sarif=codeql-go-results.sarif --github-auth-stdin= +RUN /tools/codeql/codeql github upload-results --github-url= --repository=oreos/miniature-invention --ref=refs/pull/1/merge --commit=778337f84a5abe2cda468c7abf6038b8a193cea2 --sarif=codeql-javascript-results.sarif --github-auth-stdin= diff --git a/GHAS-on-GHES-feature-matrix.md b/GHAS-on-GHES-feature-matrix.md new file mode 100644 index 0000000..5b26512 --- /dev/null +++ b/GHAS-on-GHES-feature-matrix.md @@ -0,0 +1,181 @@ +# GitHub Advanced Security (GHAS) Feature Matrix + +This document helps answer the question "is this GHAS feature available in my version of GitHub Enterprise Server?". + +The following tables include notable feature releases for GitHub Advanced Security. Each row represents a feature. The columns in the row indicate the level of support for each **supported** Enterprise Server release. Are your repositories hosted on github.com? All of these features are already available for you :+1:. + +#### Contents +- [Secret scanning](#secret-scanning) +- [Code scanning](#code-scanning) +- [Supply-chain security](#supply-chain-security) + - [Dependabot alerts](#dependabot-alerts) + - [Dependabot security updates](#dependabot-updates) + - [Dependency review and submission api](#dependency-review-and-submission-api) +- [Security Overview](#security-overview) +- [Administration](#administration) +- [Dependencies](#dependencies) + +#### How do I read this document? +Each section of this document represents a different capability of the GitHub security features. Each row in the tables represent a different feature of GHAS. The columns indicate if that feature is available in each version of GitHub Enterprise Server. + +Cells with ☑️ indicate beta support. ✅ indicates full support. + +## Release notes +* [Releases of GitHub Enterprise Server](https://docs.github.com/en/enterprise-server/admin/all-releases#releases-of-github-enterprise-server) + +|Version |3.4 |3.5 |3.6 |3.7 |3.8 |3.9| 3.10| +|---------|-----|-----|-----|-----|-----|-----|----| +|Release date| 2022-02-15 | 2022-05-10 | 2022-07-26 |2022-10-25 |2023-02-07 | 2023-06-08 | 2023-08-08 | +|Deprecation date | 2023-03-23 | 2023-06-29 | 2023-08-16 | 2023-11-08 | 2024-03-07 | 2024-06-29 | 2024-08-29 | +|| [Release notes](https://docs.github.com/en/enterprise-server@3.4/admin/release-notes)|[Release notes](https://docs.github.com/en/enterprise-server@3.5/admin/release-notes)|[Release notes](https://docs.github.com/en/enterprise-server@3.6/admin/release-notes)|[Release notes](https://docs.github.com/en/enterprise-server@3.7/admin/release-notes)|[Release notes](https://docs.github.com/en/enterprise-server@3.8/admin/release-notes)|[Release notes](https://docs.github.com/en/enterprise-server@3.9/admin/release-notes)|[Release notes](https://docs.github.com/en/enterprise-server@3.10/admin/release-notes) + +## Secret scanning +Secret scanning identifies plain text credentials inside your code repository. Learn more about secret scanning +* [Secret scanning documentation](https://docs.github.com/en/enterprise-server/code-security/secret-scanning/about-secret-scanning) +* [Secret scanning API documentation](https://docs.github.com/en/enterprise-server/rest/secret-scanning?apiVersion=2022-11-28) + +|Feature |3.4 |3.5 |3.6 |3.7 |3.8 |3.9 | 3.10 | +|------------------------------------------------------------|-----|-----|-----|-----|-----|-----|-----| +|Partner pattern count|155|169|173|173|183|200|218| +|[User defined (custom) patterns](https://docs.github.com/en/enterprise-server/code-security/secret-scanning/defining-custom-patterns-for-secret-scanning)|✅|✅|✅|✅|✅|✅|✅| +|[Enterprise level API for secret scanning](https://docs.github.com/en/enterprise-server/rest/secret-scanning?apiVersion=2022-11-28#list-secret-scanning-alerts-for-an-enterprise)|✅|✅|✅|✅|✅|✅|✅| +|[Secret scanning push protection](https://docs.github.com/en/enterprise-server/code-security/secret-scanning/protecting-pushes-with-secret-scanning)||✅|✅|✅|✅|✅|✅| +|[Dry runs for secret scanning push protection (repo level)](https://docs.github.com/en/enterprise-server/code-security/secret-scanning/defining-custom-patterns-for-secret-scanning)||✅|✅|✅|✅|✅|✅| +|[Secret scanning support for archived repos](https://github.blog/changelog/2022-02-16-secret-scanning-now-supports-archived-repositories/)||✅|✅|✅|✅|✅|✅| +|[Custom pattern events in the audit log](https://github.blog/changelog/2022-04-06-secret-scanning-custom-pattern-events-now-in-the-audit-log/)||✅|✅|✅|✅|✅|✅| +|[Push protection events in the audit log](https://docs.github.com/en/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization#secret_scanning_push_protection-category-actions)|||✅|✅|✅|✅|✅| +|[Push protection in the web editor](https://docs.github.com/en/enterprise-server/code-security/secret-scanning/protecting-pushes-with-secret-scanning#using-secret-scanning-as-a-push-protection-from-the-web-ui)|||✅|✅|✅|✅|✅| +|[Enable secret scanning at the enterprise level](https://github.blog/changelog/2022-10-06-enable-secret-scanning-for-an-enterprise-with-one-click/)||||✅|✅|✅|✅| +|[Dry runs for secret scanning custom patterns (org level)](https://github.blog/changelog/2022-02-11-secret-scanning-dry-runs-for-repository-level-custom-pattern/)||||✅|✅|✅|✅| +|[Email notification for push protection bypass](https://github.blog/changelog/2022-07-27-secret-scanning-admins-now-receive-emails-when-contributors-bypass-a-push-protection-block/)||||✅|✅|✅|✅| +|[Custom links in push protection notification](https://github.blog/changelog/2022-08-24-secret-scanning-admins-can-now-provide-a-link-to-display-when-a-push-is-blocked/)||||✅|✅|✅|✅| +|[View secret scanning enablement status at the org-level via API](https://github.blog/changelog/2021-08-24-secret-scanning-org-level-rest-api/)||||✅|✅|✅|✅| +|[Enable secret scanning at the enterprise level using the REST API](https://github.blog/changelog/2022-12-13-enable-secret-scanning-with-the-enterprise-level-rest-api/)|||||✅|✅|✅| +|[Add comment when dismissing a secret scanning alert in UI or API](https://github.blog/changelog/2022-09-29-secret-scanning-alerts-now-have-a-timeline-and-users-can-add-a-comment-when-resolving/)|||||✅|✅|✅| +|[Custom pattern creation at the enterprise level](https://docs.github.com/en/enterprise-server/code-security/secret-scanning/defining-custom-patterns-for-secret-scanning)||||||✅|✅| +|[Custom pattern alert metrics](https://docs.github.com/en/enterprise-server@3.10/code-security/secret-scanning/defining-custom-patterns-for-secret-scanning)|||||||✅| + +## Code scanning +Code scanning is a feature that you use to analyze the code in a GitHub repository to find security vulnerabilities and coding errors. Any problems identified by the analysis are shown in GitHub. +* [Code scanning documentation](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning) +* [Code scanning API documentation](https://docs.github.com/en/rest/code-scanning?apiVersion=2022-11-28) + +|Feature |3.4 |3.5 |3.6 |3.7 |3.8 |3.9 |3.10 | +|------------------------------------------------------------|-----|-----|-----|-----|-----|-----|----| +|[CodeQL "toolcache" Installed Version](https://docs.github.com/en/enterprise-server/admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance#provisioning-the-actions-for-code-scanning)|2.7.6|2.11.6|2.11.7|2.11.7|2.11.7|2.11.7|2.13.5| +|[Language support: Python, Javascript, Java, Go, C/C++, C#, Typescript](https://codeql.github.com/docs/codeql-overview/supported-languages-and-frameworks/)|✅|✅|✅|✅|✅|✅|✅| +|[Ruby Support](https://codeql.github.com/docs/codeql-overview/supported-languages-and-frameworks/)|☑️|☑️|☑️|☑️|✅|✅|✅| +|[Apple M1 support for CodeQL](https://github.blog/changelog/2021-11-10-codeql-now-supports-apple-silicon-m1/)|☑️|☑️|☑️|☑️|✅|✅|✅| +|[Org-wide code scanning alerts via the REST API](https://docs.github.com/en/rest/code-scanning?apiVersion=2022-11-28#list-code-scanning-alerts-for-an-organization)||✅|✅|✅|✅|✅|✅| +|[Add comments when dismissing alerts](https://docs.github.com/en/enterprise-server/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/managing-code-scanning-alerts-for-your-repository#dismissing--alerts)|||✅|✅|✅|✅|✅| +|[Code scanning alert comments in the pull request conversation tab](https://github.blog/changelog/2022-06-02-users-can-view-and-comment-on-code-scanning-alerts-on-the-conversation-tab-in-a-pull-request/)||||✅|✅|✅|✅| +|[Users can publish CodeQL packs to the container registry](https://docs.github.com/en/code-security/codeql-cli/using-the-codeql-cli/publishing-and-using-codeql-packs)||||✅|✅|✅|✅| +|[CodeQL query filters to exclude individual queries](https://github.blog/changelog/2022-08-31-code-scanning-customize-your-codeql-analysis-using-query-filters/)||||✅|✅|✅|✅| +|[Enterprise-wide code scanning alerts via the REST API](https://docs.github.com/en/enterprise-server/rest/code-scanning?apiVersion=2022-11-28#list-code-scanning-alerts-for-an-enterprise)||||✅|✅|✅|✅| +|[Filter API results by severity](https://github.blog/changelog/2022-11-25-filter-code-scanning-api-results-by-alert-severity/)|||||✅|✅|✅| +|[Kotlin language support](https://github.blog/changelog/2022-11-28-codeql-code-scanning-launches-kotlin-analysis-support-beta/)|||||☑️|☑️|☑️| +|[Default CodeQL setup](https://docs.github.com/en/enterprise-server/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning-for-a-repository#configuring-code-scanning-automatically)||||||✅|✅| +|[Default CodeQL setup via API](https://docs.github.com/en/enterprise-server/rest/code-scanning#update-a-code-scanning-default-setup-configuration)||||||✅|✅| +|["Enable all" functionality at the org level (API and UI)](https://docs.github.com/en/enterprise-server/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning-at-scale)||||||✅|✅| +|[Tool status page](https://docs.github.com/en/enterprise-server/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-the-tool-status-page)||||||✅|✅| +|[View org-level enablement status via the API ](https://docs.github.com/en/enterprise-server/rest/repos/repos?apiVersion=2022-11-28#list-organization-repositories)||||||✅|✅| +|[CodeQL default setup supports compiled languages](https://docs.github.com/en/enterprise-server@3.10/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages)|||||||✅| +|[Choose which language to enable or disable in CodeQL default setup](https://docs.github.com/en/enterprise-server@3.10/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-default-setup-for-code-scanning)|||||||✅| +|[Filter code scanning alerts by `path` and `language`](https://docs.github.com/en/enterprise-server@3.10/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/managing-code-scanning-alerts-for-your-repository)|||||||✅| +|[CodeQL supports C# 11](https://github.com/github/roadmap/issues/598)|||||||✅| +|[CodeQL supports Swift programming language](https://github.blog/changelog/2023-06-01-codeql-code-scanning-now-supports-swift-beta/)|||||||☑️| + + + + + +## Supply-chain security + +#### Dependabot Alerts +Dependabot alerts tell you that your code depends on a package that is insecure. +* [Dependabot alerts documentation](https://docs.github.com/en/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) +* [Dependabot alerts API](https://docs.github.com/en/enterprise-server/rest/dependabot/alerts?apiVersion=2022-11-28) + +|Feature |3.4 |3.5 |3.6 |3.7 |3.8 |3.9 |3.10 | +|------------------------------------------------------------|-----|-----|-----|-----|-----|-----|----| +|[Dependabot Alerts](https://docs.github.com/en/code-security/dependabot/dependabot-alerts/about-dependabot-alerts)|✅|✅|✅|✅|✅|✅|✅| +|[Go modules support](https://docs.github.com/en/enterprise-server/get-started/learning-about-github/github-language-support#core-languages-supported-by-github-features)|✅|✅|✅|✅|✅|✅|✅| +|[Poetry support](https://docs.github.com/en/enterprise-server/get-started/learning-about-github/github-language-support#core-languages-supported-by-github-features)|✅|✅|✅|✅|✅|✅|✅| +|[Cargo support](https://docs.github.com/en/enterprise-server/get-started/learning-about-github/github-language-support#core-languages-supported-by-github-features)|||✅|✅|✅|✅|✅| +|[Reopen dismissed alerts](https://github.blog/changelog/2022-03-07-reopen-dismissed-dependabot-alerts/)|||✅|✅|✅|✅|✅| +|[Dependabot alerts show vulnerable function calls](https://github.blog/2022-04-14-dependabot-alerts-now-surface-if-code-is-calling-vulnerability/)|||☑️|☑️|☑️|☑️|☑️| +|[Dependabot Alert timeline](https://github.blog/changelog/2022-07-28-dependabot-alerts-timeline-of-events-on-the-alert-details-page/)||||✅|✅|✅|✅| +|[Bulk Editing of Alerts](https://docs.github.com/en/code-security/dependabot/dependabot-alerts/viewing-and-updating-dependabot-alerts)||||✅|✅|✅|✅| +|[Add comment when dismissing dependabot alert](https://github.blog/changelog/2022-08-22-dependabot-alerts-optional-dismissal-comment-2/)||||✅|✅|✅|✅| +|[Dev Dependencies label](https://github.blog/2023-05-02-dependabot-relieves-alert-fatigue-from-npm-devdependencies/) ||||✅|✅|✅|✅| +|[View Dependabot enablement status via org-level API](https://github.blog/changelog/2023-02-28-dependabot-alerts-enterprise-enablement-and-status-checking/)||||✅|✅|✅|✅| +|[Receive alerts for vulnerable GitHub Actions](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot)||||✅|✅|✅|✅| +|[Dependabot alert webhooks](https://github.blog/changelog/2022-10-06-new-dependabot-alerts-webhook/)||||✅|✅|✅|✅| +|[Dependabot alerts REST API endpoint for repository org and enterprise](https://docs.github.com/en/rest/dependabot/alerts?apiVersion=2022-11-28)|||||☑️|✅|✅| +|[Export SBOM from dependency graph](https://docs.github.com/en/enterprise-server/code-security/supply-chain-security/understanding-your-software-supply-chain/exporting-a-software-bill-of-materials-for-your-repository)||||||✅|✅| +|[Dependabot can parse and update Gradle version catalogs in `settings.gradle`](https://docs.github.com/en/enterprise-server/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates)||||||✅|✅| + + + +#### Dependabot Updates +|Feature |3.4 |3.5 |3.6 |3.7 |3.8 |3.9 |3.10 | +|------------------------------------------------------------|-----|-----|-----|-----|-----|-----|----| +|[Dependabot Updates](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates)|☑️|✅|✅|✅|✅|✅|✅| +|Actions authors can automatically update dependencies within workflow files|||||✅|✅|✅| +|Dart and Flutter (using Pub) support for updates|||||✅|✅|✅| +|[Automatically pause pull request activity after 90 days of inactivity](https://docs.github.com/en/enterprise-server/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates#about-automatic-deactivation-of-dependabot-updates)||||||✅|✅| +|[Dependabot updates supports pnpm](https://github.blog/changelog/2023-06-12-dependabot-version-updates-now-supports-pnpm/)|||||||✅| + +#### Dependency Review and submission API +Dependency review helps you understand dependency changes and the security impact of these changes at every pull request. +* [Dependency review docs](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-dependency-review) +* [Dependency review API docs](https://docs.github.com/en/rest/dependency-graph/dependency-review?apiVersion=2022-11-28) + +|Feature |3.4 |3.5 |3.6 |3.7 |3.8 |3.9 |3.10 | +|------------------------------------------------------------|-----|-----|-----|-----|-----|-----|----| +|[Dependency Review](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-dependency-review)|✅|✅|✅|✅|✅|✅|✅| +|[Enforcement Action](https://github.blog/changelog/2022-04-06-github-action-for-dependency-review-enforcement/)|||✅|✅|✅|✅|✅| +|[Dependency Submission API](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api)||||✅|✅|✅|✅| + + +## Security Overview +Security overview provides high-level summaries of the security status of an organization or enterprise and makes it easy to identify repositories that require intervention. +* [Security Overview documentation](https://docs.github.com/en/enterprise-server/code-security/security-overview/about-security-overview) + +|Feature |3.4 |3.5 |3.6 |3.7 |3.8 |3.9 |3.10| +|------------------------------------------------------------|-----|-----|-----|-----|-----|-----|----| +|[Security Overview](https://docs.github.com/en/enterprise-server/code-security/security-overview/about-security-overview)|✅|✅|✅|✅|✅|✅|✅| +|Organization view|☑️|✅|✅|✅|✅|✅|✅| +|Enterprise view||☑️|☑️|✅|✅|✅|✅| +|Organization-level Code Scanning Alert View||✅|✅|✅|✅|✅|✅| +|Organization-level Dependabot Alert View||✅|✅|✅|✅|✅|✅| +|Enterprse-level view of Dependabot alerts|||✅|✅|✅|✅|✅| +|Enterprse-level view of code scanning alerts||||✅|✅|✅|✅| +|Enterprse-level view of secret scanning alerts||||✅|✅|✅|✅| +|Coverage and Risk Security Overview pages|||||☑️|☑️|✅| +|[Filter alerts by repo topic](https://docs.github.com/en/enterprise-server/code-security/security-overview/filtering-alerts-in-security-overview)||||||✅|✅| +|[Filter alerts by team](https://docs.github.com/en/enterprise-server/code-security/security-overview/filtering-alerts-in-security-overview)||||||✅|✅| +|[Enable GHAS features in security overview](https://docs.github.com/en/enterprise-server/code-security/security-overview/about-security-overview)||||||✅|✅| +|[Enterprise-level security coverage and risk dashboards](https://docs.github.com/en/enterprise-server@3.10/code-security/security-overview/about-security-overview#about-security-overview-for-enterprises)|||||||✅| + +## Administration +|Feature |3.4 |3.5 |3.6 |3.7 |3.8 |3.9 |3.10 +|------------------------------------------------------------|-----|-----|-----|-----|-----|-----|----| +|[Security Managers Role](https://docs.github.com/en/enterprise-server/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization)|✅|✅|✅|✅|✅|✅|✅| +|[Manage Security Managers role via the API](https://docs.github.com/en/enterprise-server/rest/orgs/security-managers?apiVersion=2022-11-28)||||✅|✅|✅|✅| + +# Dependencies +This section calls out the dependencies required to enable GitHub Advanced Security on GitHub Enterprise Server. + +| Feature | GHAS license
required? | GitHub Actions
required? | GitHub Connect
required? | Documentation | Notes | +|---|---|---|---|---|---| +| Security Overview

DescriptionKnow what needs attention throughout the entire SDLC
| No * | No | No | [Feature Docs](https://docs.github.com/en/enterprise-server@latest/code-security/security-overview/about-the-security-overview) | * Features not needing a GHAS license will still show up | +| Dependency Graph

DescriptionParse manifest and lock files in your repository
| No | No | No | [Feature Docs](https://docs.github.com/en/enterprise-server@latest/admin/code-security/managing-supply-chain-security-for-your-enterprise/enabling-the-dependency-graph-for-your-enterprise) | Enabling this feature will reload some services on the appliance. | +| Dependabot Alerts

DescriptionKnow which of :point_up: have open CVEs
| No | No | Yes | [Feature Docs](https://docs.github.com/en/enterprise-server@latest/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) | [GitHub Connect](https://docs.github.com/en/enterprise-server@latest/admin/configuration/configuring-github-connect/enabling-dependabot-for-your-enterprise) dependency and data transmission details | +| Dependabot Security Updates

DescriptionOne-click "enable all" to send PRs updating :point_up:
| No | Yes | Yes | [Feature Docs](https://docs.github.com/en/enterprise-server@latest/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates) | Requires a runner with Docker and internet connectivity to open PRs ([specs](https://docs.github.com/en/enterprise-server@latest/admin/github-actions/enabling-github-actions-for-github-enterprise-server/managing-self-hosted-runners-for-dependabot-updates))

As of GHES 3.8, will not require internet connectivity _if_ private registry is configured | +| Dependabot Updates

DescriptionAllows Dependabot to process optional updates using `~/.github/dependabot.yml` file
| No | Yes | Yes | [Feature Docs](https://docs.github.com/en/enterprise-server@latest/code-security/dependabot/dependabot-version-updates) | Same requirements as :point_up: - this just allows the same "non-security" updates using the same flexible configuration file as GitHub.com | +| Dependency Review

DescriptionInspect dependencies at pull request, blocking merges that add more security vulnerabilities
| Yes | Yes | Yes | [Feature Docs](https://docs.github.com/en/enterprise-server@latest/admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-dependency-review-for-your-appliance) | Does not require the build to be moved into GitHub Actions, but needs a runner to inspect manifests | +| CodeQL

DescriptionHighly accurate static analysis tool, flexible and extensible query language
| Yes | No * | No * | [Feature Docs](https://docs.github.com/en/enterprise-server@latest/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql) | * CodeQL can be installed in your existing build system ([directions](https://docs.github.com/en/enterprise-server@latest/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/installing-codeql-cli-in-your-ci-system)) and/or be used on GitHub Actions with self-hosted runners ([directions](https://docs.github.com/en/enterprise-server@latest/admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance#running-code-scanning-using-github-actions))

* GitHub Connect is not required, but it makes keeping the CodeQL queries up-to-date easier.

* [codeql-action-sync-tool](https://github.com/github/codeql-action-sync-tool) is the offline updater without Connect.

* Code Scanning default setup requires runners with the `code-scanning` label applied. | +| Upload SARIF files from other tools

DescriptionView security results from other tools using SARIF file uploads
| Yes | No | No | [Feature Docs](https://docs.github.com/en/enterprise-server@latest/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github) | Many other tools support the SARIF interchange format. This feature provides a single pane of glass into the entire codebase. | +| Secret scanning

DescriptionLook at the present and all history for secrets, including partner patterns and custom regex
| Yes | No | No | [Feature Docs](https://docs.github.com/en/enterprise-server@latest/code-security/secret-scanning) | | +| Push protection for secrets

DescriptionBlock commits containing partner patterns and custom regex from GitHub, preventing compromise
| Yes | No | No | [Feature Docs](https://docs.github.com/en/enterprise-server@latest/code-security/secret-scanning/protecting-pushes-with-secret-scanning) | Bare metal hypervisors may require an additional CPU flag, as outlined [here](https://docs.github.com/en/enterprise-server@latest/admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-secret-scanning-for-your-appliance) | diff --git a/README.md b/README.md index 5e759fc..5b897dc 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,46 @@ # Advanced Security Material -A place for resources to help you understand and use GitHub Advanced Security +A place for resources to help you understand and use GitHub Advanced Security (GHAS). Browse the directories in this repository for resources and documentation. To help you get started with GHAS, we've provided some introductory documentation in this file. + +## Get started with GitHub Advanced Security +The following list of links are great resources to get you started on learning how to use, deploy, and manage GitHub Advanced Security in your environment. + +New to GitHub Advanced Security? Start with [GitHub security features](https://docs.github.com/en/enterprise-cloud@latest/code-security/getting-started/github-security-features) :+1: + +### Code Scanning +- [About GitHub Code Scanning](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning) +- [Configuring Code Scanning](https://docs.github.com/en/enterprise-cloud@latest/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning) +- [Integrating other tools with GHAS](https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning) + +### CodeQL +- [Meet CodeQL](https://codeql.github.com/) +- [CodeQL Documentation](https://codeql.github.com/docs/) +- [CWE Query Mapping Documentation](https://codeql.github.com/codeql-query-help/codeql-cwe-coverage) +- [Running additional queries](https://docs.github.com/en/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#running-additional-queries) +- [CodeQL CLI Docs](https://codeql.github.com/docs/codeql-cli/getting-started-with-the-codeql-cli) +- [Running CodeQL in your CI System](https://docs.github.com/en/github/finding-security-vulnerabilities-and-errors-in-your-code/running-codeql-code-scanning-in-your-ci-system) + +### Secret Scanning +- [About Secret Scanning](https://docs.github.com/en/code-security/secret-scanning/about-secret-scanning) +- [Supported secret patterns](https://docs.github.com/en/code-security/secret-scanning/secret-scanning-patterns#supported-secrets-for-partner-patterns) +- [Defining custom secret patterns](https://docs.github.com/en/enterprise-cloud@latest/code-security/secret-scanning/defining-custom-patterns-for-secret-scanning) + +### Supply Chain Security (Dependabot) +- [About](https://docs.github.com/en/enterprise-cloud@latest/code-security/supply-chain-security/understanding-your-software-supply-chain/about-supply-chain-security) +- [Dependency Graph](https://docs.github.com/en/enterprise-cloud@latest/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph) +- [Dependabot Alerts](https://docs.github.com/en/enterprise-cloud@latest/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) +- [Dependabot Security Updates](https://docs.github.com/en/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates) +- [GitHub Advisory Database](https://github.com/advisories) +- [Dependabot Quickstart Guide](https://docs.github.com/en/code-security/getting-started/dependabot-quickstart-guide) + +### Security Overview +- [About Security Overview](https://docs.github.com/en/code-security/security-overview/about-the-security-overview) +- [Managing alerts in your repository](https://docs.github.com/en/enterprise-cloud@latest/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/managing-code-scanning-alerts-for-your-repository) + +### Other Resources +- [SARIF Tutorials](https://github.com/microsoft/sarif-tutorials) +- [GitHub Advanced Security Learning Path](https://docs.microsoft.com/en-us/users/githubtraining/collections/rqymc6yw8q5rey) +- [Scaling GHAS in Your Organization](https://resources.github.com/downloads/Whitepaper-Scaling-GHAS-in-an-Enterprise.pdf) +- [The Complete Guide to Developer-first Security](https://resources.github.com/downloads/GitHubAdvanced%20SecurityEbook.pdf) +- [GitHub Checkout - Code Scanning (video)](https://www.youtube.com/watch?v=z0wvGf3O69E) +- [GitHub Checkout - Secret Scanning (video)](https://www.youtube.com/watch?v=aoL7pDrXt74) +- [GitHub Checkout - Viewing and Managing your Dependencies (video)](https://www.youtube.com/watch?v=gNd_TGdZ1xc) diff --git a/advanced-security-material.md b/advanced-security-material.md index 20a9913..18a4554 100644 --- a/advanced-security-material.md +++ b/advanced-security-material.md @@ -13,8 +13,8 @@ - [ ] Javascript: https://www.youtube.com/watch?v=pYzfGaLTqC0 #### CodeQL Resources: -- [ ] QL Tutorials: https://help.semmle.com/QL/learn-ql/beginner/ql-tutorials.html -- [ ] CodeQL for VS Code: https://help.semmle.com/codeql/codeql-for-vscode/procedures/about-codeql-for-vscode.html +- [ ] QL Tutorials: https://codeql.github.com/docs/writing-codeql-queries/ql-tutorials/ +- [ ] CodeQL for VS Code: https://codeql.github.com/docs/codeql-for-visual-studio-code/ - [ ] VS Code starter workspace to use with the CodeQL VS extension: https://github.com/github/vscode-codeql-starter - [ ] CodeQL CTF: https://securitylab.github.com/ctf - [ ] Read about contributing to CodeQL Queries: https://github.com/github/codeql/blob/main/CONTRIBUTING.md @@ -34,7 +34,7 @@ - [ ] Configure code scanning: https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning - [ ] Configuring builds for Compiled Languages: https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-the-codeql-workflow-for-compiled-languages - [ ] Running additional queries: https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#running-additional-queries - - [ ] Built-in Queries: https://help.semmle.com/QL/ql-built-in-queries.html + - [ ] Built-in Queries: https://github.com/github/codeql, https://github.com/github/codeql-go - For example, js query suites: https://github.com/github/codeql/tree/master/javascript/ql/src/codeql-suites - [ ] Troubleshooting code scanning workflow: https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/troubleshooting-the-codeql-workflow @@ -46,4 +46,4 @@ https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerab - [ ] Jenkins + CodeQL CLI: https://github.com/kllund/sample-pipeline-files/blob/main/Jenkinsfile-template-with-codeql-cli-bundle #### OSS Issue Tracking -- [ ] GitHub Code Scanning + Jira: https://github.com/github/codescanning-jira-integration +- [ ] GitHub Code Scanning + Jira: https://github.com/github/ghas-jira-integration diff --git a/advanced-security-reporting.md b/advanced-security-reporting.md deleted file mode 100644 index fb9eae2..0000000 --- a/advanced-security-reporting.md +++ /dev/null @@ -1,11 +0,0 @@ -# Open Source Reporting Tools - -- Dependabot - - [ ] https://github.com/mr-sherman/get-dependency-alerts-in-org - - [ ] https://github.com/tonycch/get-dependabot-alerts-sample -- Code scanning - - [ ] https://github.com/jhutchings1/get-code-scanning-alerts-in-org-sample - - [ ] https://github.com/issc29/generate-vuln-report -- Secret scanning - - [ ] GHES 3.1+: https://github.com/cmboling/get-secret-scanning-alerts-in-org-sample/tree/ghes/base-url-included - - [ ] dotcom/GHEC: https://github.com/cmboling/get-secret-scanning-alerts-in-org-sample diff --git a/code-scanning-guides/setup-codeql-cli.md b/code-scanning-guides/setup-codeql-cli.md index d233c3f..be7fa96 100644 --- a/code-scanning-guides/setup-codeql-cli.md +++ b/code-scanning-guides/setup-codeql-cli.md @@ -1,6 +1,6 @@ ### Getting started with the CodeQL CLI -When you want to generate a CodeQL database locally and run the pre-compiled queries against, this is the way to go. +When you want to generate a CodeQL database locally and run the pre-compiled queries against it, this is the way to go. First let's download the CodeQL bundle! Head over [here](https://github.com/github/codeql-action/releases ) and download the approprate bundle for your operating system. Once it's downloaded, untar the content to a CodeQL home folder and you can add CodeQL to your path if you'd like @@ -15,9 +15,6 @@ Check to make sure you can use the CodeQL CLI codeql --version ``` -You can see in this example how the CodeQL CLI is used in a [workflow](https://github.com/advanced-security/javascript-codeql-cli-test-workflow/blob/main/.github/workflows/codeql-analysis.yml). -Note that it always downloads the latest CodeQL bundle for Linux. In your case, choose the bundle that best fits your operating system. - Now we need to use the CodeQL CLI on an actual repository. Let's start here with our [GHAS training material](https://github.com/ghas-bootcamp/ghas-bootcamp) There's multiple languages being used here, so for the purposes of this tutorial let's try to scan the Javascript portions of the codebase. @@ -29,7 +26,7 @@ Clone this repository and `cd` into it. The first thing we gotta do when it comes to CodeQL analysis is to create a CodeQL database. When it comes to interpreted languages and Go, CodeQL will use an autobuild.sh script that will extract the source code and create a snapshot database. When it comes to compiled languages, we require to build the source code in order to trace the build and create a snapshot database of it. -You can rely on the autobuild.sh script as well, or you can supply your own build instructions via `--comand` flag, which can be used when invoking the `codeql database create` command. +You can rely on the autobuild.sh script as well, or you can supply your own build instructions via the `--command` flag, which can be used when invoking the `codeql database create` command. Please review this [list](https://codeql.github.com/docs/codeql-overview/supported-languages-and-frameworks/) of currently supported languages and frameworks. @@ -41,9 +38,9 @@ CodeQL will create the `db` directory and will choose the autobuild.sh script fo CodeQL will also finalize the database at the specified `db` directory. Within your codeql database directory (in this case `db`) you should notice a db-javascript directory which contains the db schemes and a src.zip which contains the source that was extracted. -#### Importing the CodeQL database to Visual Studios +#### Optional: Importing the CodeQL database to Visual Studios You can actually take this database and import it to your Visual Studios workspace. -To get started on that, please go to this repository and follow the instructions on how to setup the CodeQL starter workspace, as well as installing the CodeQL plugin. +To get started on that, please go to this [repository](https://github.com/github/vscode-codeql-starter) and follow the instructions on how to setup the CodeQL starter workspace, as well as installing the CodeQL plugin. Once you have the CodeQL plugin installed, import the database you created in this step and try to run a javascript query against the database. @@ -77,13 +74,13 @@ Failure to do so, in particular on a pull request, can cause confusion in that C This step is typically used when you want to see the SARIF in the Code Scanning alerts UI. It's typically used when you want to post results to the default branch of a repository for the first time (baseline analysis) or to a pull request to see any security alert annotations. Here are some advanced things to note: -- When posting the analysis for the first time to a default analysis, make sure you define a `--sarif-category`. That way for the analyses for subsequent pull requests can also share the same category value. +- When posting the analysis for the first time to a default analysis, make sure you define a `--sarif-category`. That way the analyses for subsequent pull requests can also share the same category value. Note that this kind of depends on how you're running the builds (whether or not you've broken down a monorepo into separate analyses or you have multiple scans due to multiple languaages) but typically just starting out, just make sure to have the same category value for subsequent scans, so that Code Scannning can easily figure out what the basline analysis is to compare subsequent analyses. The `--ref` and `--commit` flag combinations can be one of the following: -- `refs/pulls//merge` + HEAD commit -- `refs/heads/` + MERGE commit +- `refs/pulls//merge` + MERGE commit +- `refs/heads/` + HEAD commit - ` curl -H "Accept: application/vnd.github.v3+json" \\n -H "Authorization: token $GH_TOKEN" \\n https://api.github.com/repos///pulls/ | jq '.merge_commit_sha'` - The merge commit is a commit created to make sure PR checks are ran; this commit doesn't exist in the actual source tree/`git log`. diff --git a/code-scanning-guides/synthetic-applications/owasp-webgoat.md b/code-scanning-guides/synthetic-applications/owasp-webgoat.md new file mode 100644 index 0000000..dd92456 --- /dev/null +++ b/code-scanning-guides/synthetic-applications/owasp-webgoat.md @@ -0,0 +1,15 @@ +# OWASP WebGoat + +[A full Actions workflow can be found here](./owasp-webgoat.yml) + +## Common Issues + +Scanning OWASP WebGoat can have some issues right out of the box where CodeQL might find very little or worse not find anything at all. +This is due to the following: + +1. WebGoat uses JDK 17 + - Action uses JDK 8 by default +2. Uses Project Lombok + - Future support will be coming to CodeQL natively +3. Dependencies are not all present in Dependency Graph + - Using [Submission API](https://docs.github.com/en/enterprise-cloud@latest/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api#using-pre-made-actions) diff --git a/code-scanning-guides/synthetic-applications/owasp-webgoat.yml b/code-scanning-guides/synthetic-applications/owasp-webgoat.yml new file mode 100644 index 0000000..f38ee87 --- /dev/null +++ b/code-scanning-guides/synthetic-applications/owasp-webgoat.yml @@ -0,0 +1,61 @@ +name: "CodeQL" + +on: + push: + branches: [ main ] + pull_request: + # The branches below must be a subset of the branches above + branches: [ main ] + workflow_dispatch: + +permissions: + actions: read + contents: read + security-events: write + +env: + # in the future, this flag will not be needed + CODEQL_EXTRACTOR_JAVA_RUN_ANNOTATION_PROCESSORS: true + +jobs: + analyze: + name: Analyze + runs-on: ubuntu-latest + + strategy: + fail-fast: false + matrix: + language: [ 'java', 'javascript' ] + + steps: + - uses: actions/checkout@v2 + + # WebGoat requires Java/JDK 17 + - name: Set up JDK 17 + if: matrix.language == 'java' + uses: actions/setup-java@v3 + with: + distribution: 'temurin' + java-version: 17 + architecture: x64 + + - name: Initialize CodeQL + uses: github/codeql-action/init@v2 + with: + languages: ${{ matrix.language }} + # [optional] enabled extended queries + # queries: +security-extended,security-and-quality + # [optional] Field Config - standard packs, extensions, and extra packs + config-file: advanced-security/codeql-queries/config/codeql.yml@main + + - name: Autobuild + uses: github/codeql-action/autobuild@v2 + + # Run the Analysis + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v2 + + # Submit Maven Dependency Tree to GitHub + - name: Maven Dependency Tree Dependency Submission + if: matrix.language == 'java' + uses: advanced-security/maven-dependency-submission-action@v3.0.2 diff --git a/code-scanning-scripts/README.md b/code-scanning-scripts/README.md new file mode 100644 index 0000000..e902fe3 --- /dev/null +++ b/code-scanning-scripts/README.md @@ -0,0 +1,5 @@ +### Code scanning scripts + + +- [ ] [Code scanning bulke enable](https://github.com/mario-campos/gh-code-scanning) +- [ ] [Run CodeQL analysis on a pull request](https://github.com/advanced-security/advanced-security-material/blob/main/code-scanning-scripts/run-pr-codeql-analysis.sh) diff --git a/code-scanning-scripts/combine-n-databases.sh b/code-scanning-scripts/combine-n-databases.sh new file mode 100644 index 0000000..2e7f73c --- /dev/null +++ b/code-scanning-scripts/combine-n-databases.sh @@ -0,0 +1,16 @@ +#!/usr/bin/env bash + +# For n number of dirs, initialise each of them. In this example I have two dirs at the root: +codeql database init dbs/db-js1 --language=javascript --source-root dir1 --overwrite +codeql database init dbs/db-js2 --language=javascript --source-root dir2 --overwrite + +# After db skeletons are created, use the trace command to call out the extractor/add build instructions +codeql database trace-command dbs/db-js1 -- /Users/cmboling/Projects/codeql-home/codeql-latest/javascript/tools/autobuild.sh +codeql database trace-command dbs/db-js2 -- /Users/cmboling/Projects/codeql-home/codeql-latest/javascript/tools/autobuild.sh + +# Then import n unfinalized dbs to the target db +codeql database import dbs/db-js1 db-js2 +codeql database finalize --finalize-dataset db-js1 + +# Analyze target db as usual +codeql database analyze db-js1 javascript-code-scanning.qls --format=sarif-latest --output=codeql-javascript-results.sarif diff --git a/code-scanning-scripts/get-languages.sh b/code-scanning-scripts/get-languages.sh new file mode 100644 index 0000000..5190e61 --- /dev/null +++ b/code-scanning-scripts/get-languages.sh @@ -0,0 +1,5 @@ +#!/usr/bin/env bash + +curl -H "Accept: application/vnd.github.v3+json" -H "Authorization: token $GH_TOKEN" \ +https://api.github.com/repos/advanced-security/ghas-bootcamp-dryrun/languages | \ +jq 'with_entries(select([.key] | inside(["Go", "Java", "JavaScript", "Python", "C++", "C#", "C", "TypeScript"])) | if .key == "C" then .key = "cpp" else . end | if .key == "C#" then .key = "csharp" else . end | if .key == "C++" then .key = "cpp" else . end | if .key == "Go" then .key = "go" else . end | if .key == "Java" then .key = "java" else . end | if .key == "JavaScript" then .key = "javascript" else . end | if .key == "Python" then .key = "python" else . end | if .key == "TypScript" then .key = "typescript" else . end)' | jq "keys" diff --git a/code-scanning-scripts/run-pr-codeql-analysis.sh b/code-scanning-scripts/run-pr-codeql-analysis.sh index b0f539b..67c66cd 100644 --- a/code-scanning-scripts/run-pr-codeql-analysis.sh +++ b/code-scanning-scripts/run-pr-codeql-analysis.sh @@ -19,17 +19,14 @@ CODEQL_SARIF_CATEGORY=.github/workflows/codeql-analysis.yml:analyze/language:go # run a single language analysis for a PR -# remove db -rm -rf $CODEQL_DATABASE - -# get mergit commit sha +# get merge commit sha GH_MERGE_COMMIT_SHA=$(curl -H "Accept: application/vnd.github.v3+json" -H "Authorization: token $GH_TOKEN" https://api.github.com/repos/$GH_ORG/$GH_REPO/pulls/$GH_PULL_REQUEST_NUMBER | jq '.merge_commit_sha' | sed -e 's/^"//' -e 's/"$//') # check codeql --version codeql --version # codeql database create -codeql database create $CODEQL_DATABASE --language=$CODEQL_LANGUAGE +codeql database create $CODEQL_DATABASE --language=$CODEQL_LANGUAGE --overwrite # codeql database analyze codeql database analyze $CODEQL_DATABASE $CODEQL_QUERY_SUITE --output=$CODEQL_SARIF_RESULTS --sarif-category=$CODEQL_SARIF_CATEGORY --format=sarif-latest diff --git a/code-scanning-third-party-integrations.md b/code-scanning-third-party-integrations.md index d98eaaa..055263b 100644 --- a/code-scanning-third-party-integrations.md +++ b/code-scanning-third-party-integrations.md @@ -52,8 +52,10 @@ ### Kotlin - [Detekt](https://github.com/detekt/detekt) (Code Quality) - - [Kotlin Example](https://github.com/octodemo/KotlinGoat/blob/master/.github/workflows/detekt-analysis-yml) + - [Kotlin Example](https://github.com/octodemo/KotlinGoat/blob/master/.github/workflows/detekt-analysis.yml) - [MobSF](https://github.com/MobSF/Mobile-Security-Framework-MobSF) +- [ShiftLeft](https://github.com/ShiftLeftSecurity/scan-action) + - [Kotlin Example](https://github.com/octodemo/KotlinGoat/blob/master/.github/workflows/shiftleft-analysis.yml) ### Lightning (Aura and LWC) @@ -102,6 +104,10 @@ - [MobSF](https://github.com/MobSF/Mobile-Security-Framework-MobSF) +### T-SQL + +- [TSQLLint](https://github.com/tsqllint/tsqllint) via [Codacy](https://github.com/codacy/codacy-analysis-cli-action) action + ### Visualforce - [CodeScan](https://github.com/codescan-io/codescan-scanner-action) @@ -128,6 +134,7 @@ ### CloudFormation - [KICS](https://github.com/Checkmarx/kics) +- [Action for CloudFormation Linter](https://github.com/ScottBrenner/cfn-lint-action) ### Docker diff --git a/code-scanning-workflows/azure-pipeline-00.yml b/code-scanning-workflows/azure-pipeline-00.yml new file mode 100644 index 0000000..ef773c3 --- /dev/null +++ b/code-scanning-workflows/azure-pipeline-00.yml @@ -0,0 +1,54 @@ +steps: + # Download the CodeQL CLI and query packs... + # Check out the repository ... + + # Tasks prior to executing the build, e.g. restore NuGet dependencies... + + # Initialize the CodeQL database. + # In this example, the CodeQL CLI has been downloaded and placed on the PATH. + # If no language is specified, a GitHub Apps or personal access token must be passed through stdin + # to autodetect the language. + - task: CmdLine@1 + displayName: Initialize CodeQL database + inputs: + # Assumes the source code is checked out to the current working directory. + # Creates a database at `/db` + script: "codeql database init --language csharp --trace-process-level 3 --source-root . --begin-tracing db" + + # Read the generated environment variables and values, + # and set them so they are available for subsequent commands + # in the build pipeline. This is done in PowerShell in this example. + - task: PowerShell@1 + displayName: Set CodeQL environment variables + inputs: + targetType: inline + script: > + $json = Get-Content $(System.DefaultWorkingDirectory)/db/temp/tracingEnvironment/start-tracing.json | ConvertFrom-Json + $json.PSObject.Properties | ForEach-Object { + $template = "##vso[task.setvariable variable=" + $template += $_.Name + $template += "]" + $template += $_.Value + echo "$template" + } + + # Execute the pre-defined build step. Note the `msbuildArgs` variable. + - task: VSBuild@1 + inputs: + solution: '**/*.sln' + # Disable MSBuild shared compilation for C# builds. + msbuildArgs: /p:OutDir=$(Build.ArtifactStagingDirectory) /p:UseSharedCompilation=false + platform: Any CPU + configuration: Release + # Execute a clean build, in order to remove any existing build artifacts prior to the build. + clean: True + displayName: Visual Studio Build + + - task: CmdLine@2 + displayName: Finalize CodeQL database + inputs: + script: 'codeql database finalize db' + + # Other tasks go here, + # e.g. `codeql database analyze` + # and `codeql github upload-results` ... diff --git a/code-scanning-workflows/code-scanning-codeql-cli-example-00.yml b/code-scanning-workflows/code-scanning-codeql-cli-example-00.yml new file mode 100644 index 0000000..8f9bebf --- /dev/null +++ b/code-scanning-workflows/code-scanning-codeql-cli-example-00.yml @@ -0,0 +1,127 @@ +# For most projects, this workflow file will not need changing; you simply need +# to commit it to your repository. +# +# You may wish to alter this file to override the set of languages analyzed, +# or to provide custom queries or build logic. +# +# ******** NOTE ******** +# We have attempted to detect the languages in your repository. Please check +# the `language` matrix defined below to confirm you have the correct set of +# supported CodeQL languages. +# +name: "CodeQL" + +on: + push: + branches: [ "main" ] + pull_request: + # The branches below must be a subset of the branches above + branches: [ "main" ] + schedule: + - cron: '20 21 * * 3' + +jobs: + analyze: + name: Analyze + # Runner size impacts CodeQL analysis time. To learn more, please see: + # - https://gh.io/recommended-hardware-resources-for-running-codeql + # - https://gh.io/supported-runners-and-hardware-resources + # - https://gh.io/using-larger-runners + # Consider using larger runners for possible analysis time improvements. + runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }} + timeout-minutes: ${{ (matrix.language == 'swift' && 120) || 360 }} + permissions: + actions: read + contents: read + security-events: write + + strategy: + fail-fast: false + matrix: + language: [ 'go', 'java', 'javascript', 'python' ] + # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby', 'swift' ] + # Use only 'java' to analyze code written in Java, Kotlin or both + # Use only 'javascript' to analyze code written in JavaScript, TypeScript or both + # Learn more about CodeQL language support at https://aka.ms/codeql-docs/language-support + + steps: + - name: Checkout repository + uses: actions/checkout@v3 + + # Install Java if necessary + - if: matrix.language == 'java' + name: Setup Java + uses: actions/setup-java@v3 + with: + distribution: 'adopt' + java-version: '15' + + # Initialize the CodeQL tools for scanning. + - name: Initialize CodeQL + run: | + gh extensions install github/gh-codeql + gh codeql set-version latest + gh codeql pack download codeql/${{ matrix.language }}-queries + env: + GH_TOKEN: ${{ github.token }} + + # Create a CodeQL database and start tracing for compiled languages + - name: Create CodeQL Database + run: | + gh codeql database init --begin-tracing --language=${{ matrix.language }} --source-root=${{ env.GITHUB_WORKSPACE }} ${{ matrix.language }}-db + env: + GH_TOKEN: ${{ github.token }} + + - if: matrix.language == 'java' + name: Build Java Code + run: | + source ../${{ matrix.language }}-db/temp/tracingEnvironment/start-tracing.sh + mvn clean install + working-directory: ./storage-service + + - if: matrix.language == 'go' + name: Build Go Code + run: | + source ../${{ matrix.language }}-db/temp/tracingEnvironment/start-tracing.sh + go build + working-directory: ./gallery-service + + - name: Traceless Database Build (Python/JS) + if: contains(fromJSON('["javascript", "python"]'), ${{ matrix.language }}) + run: | + gh codeql database trace-command --index-traceless-dbs ${{ matrix.language }}-db + env: + GH_TOKEN: ${{ github.token }} + + # Finalize the database + - name: Finalize database + run: | + gh codeql database finalize ${{ matrix.language }}-db + env: + GH_TOKEN: ${{ github.token }} + + # The --sarif-category must be set for each language's database + - name: Analyze database + run: | + gh codeql database analyze \ + --format="sarif-latest" \ + --sarif-category="codeql-scan:${{ matrix.language }}" \ + --output=${{ matrix.language }}-db.sarif \ + -j=0 \ + --sarif-add-query-help --sarif-add-snippets \ + ${{matrix.language}}-db + env: + GH_TOKEN: ${{ github.token }} + + # Upload the CodeQL scan results + - name: Upload results + run: | + echo ${{ github.token }} | \ + gh codeql github upload-results \ + --sarif=${{ matrix.language }}-db.sarif \ + --repository=$GITHUB_REPOSITORY \ + --ref=$GITHUB_REF \ + --commit=$GITHUB_SHA \ + --github-auth-stdin + env: + GH_TOKEN: ${{ github.token }} diff --git a/code-scanning-workflows/reusable_code_scanning-00.yml b/code-scanning-workflows/reusable_code_scanning-00.yml new file mode 100644 index 0000000..f2f9c03 --- /dev/null +++ b/code-scanning-workflows/reusable_code_scanning-00.yml @@ -0,0 +1,138 @@ +name: "Code Analysis" + +# this workflow can be stored in a centralized repo and called externally +# jobs: +# code_analysis: +# uses: [REPO]/.github/workflows/code_analysis.yml@main + +on: + workflow_dispatch: #for testing + workflow_call: #for composition + +jobs: + detect-lang: + runs-on: ubuntu-latest + outputs: + linguist_languages: ${{ steps.linguist_languages.outputs.languages }} + codeql_languages: ${{ steps.codeql_languages.outputs.languages }} + steps: + - id: linguist_languages + run: echo "::set-output name=languages::$(gh api repos/${GITHUB_REPOSITORY}/languages)" + - id: codeql_languages + # builds the list of languages which are both present in the repo and supported by CodeQL + # remove from the dictionary the languages that should not be considered (e.g .-[null, "go"]) + run: | + echo "::set-output name=languages::$(gh api repos/${GITHUB_REPOSITORY}/languages -q '[ + {"C":"cpp", "C++":"cpp", "C#":"csharp", "Go":"go", "Java":"java", "JavaScript":"javascript", + "TypeScript":"javascript", "Python":"python", "Ruby":"ruby"}[keys[]]] | unique -[null]')" + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + codeql-analysis: + needs: [detect-lang] + # skip the analysis when the list of languages is empty + if: needs.detect-lang.outputs.codeql_languages != '[]' + runs-on: ubuntu-latest + permissions: + actions: read + contents: read + security-events: write + + strategy: + fail-fast: false + matrix: + language: ${{ fromJSON(needs.detect-lang.outputs.codeql_languages) }} + # eventually exclude languages + exclude: + - language: ruby + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + with: + fetch-depth: 0 + + # Initializes the CodeQL tools for scanning. + - name: Initialize CodeQL + uses: github/codeql-action/init@v1 + with: + languages: ${{ matrix.language }} + + # Autobuild attempts to build any compiled languages (C/C++, C#, or Java). + # If this step fails, then you should remove it and run the build manually (see below) + - name: Autobuild + uses: github/codeql-action/autobuild@v1 + + # perform the analysis + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v1 + + tsqllint-analysis: + name: Codacy Security Scan + needs: [detect-lang] + if: contains(needs.detect-lang.outputs.linguist_languages, '"TSQL"') + runs-on: ubuntu-latest + steps: + # Checkout the repository to the GitHub Actions runner + - name: Checkout code + uses: actions/checkout@v2 + + # Execute Codacy Analysis CLI and generate a SARIF output with the security issues identified during the analysis + - name: Run Codacy Analysis CLI + uses: codacy/codacy-analysis-cli-action@1.1.0 + with: + tool: tsqllint + verbose: true + output: ${{ runner.temp }}/results.sarif + format: sarif + # Adjust severity of non-security issues + gh-code-scanning-compat: true + # Force 0 exit code to allow SARIF file generation + # This will handover control about PR rejection to the GitHub side + max-allowed-issues: 2147483647 + + - name: Rewrite Codacy SARIF urls to relative paths + run: sed -i 's#"uri":"file:///codacy/#"uriBaseId":"%SRCROOT%","uri":"#g' ${{ runner.temp }}/results.sarif + + # Upload the SARIF file generated in the previous step + - name: Upload SARIF results file + uses: github/codeql-action/upload-sarif@v1 + with: + sarif_file: ${{ runner.temp }}/results.sarif + + - uses: actions/upload-artifact@v2 + with: + name: results.sarif + path: ${{ runner.temp }}/results.sarif + + # + # Runs Rubocop for Ruby + # + rubocop-analysis: + name: Rubocop Security Scan + needs: [detect-lang] + if: contains(needs.detect-lang.outputs.linguist_languages, '"Ruby"') + runs-on: ubuntu-latest + strategy: + fail-fast: false + steps: + - name: Checkout repository + uses: actions/checkout@v2 + # If running on a self-hosted runner, check it meets the requirements + # listed at https://github.com/ruby/setup-ruby#using-self-hosted-runners + - name: Set up Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: 2.6 + - name: Install Code Scanning integration + run: gem install 'code-scanning-rubocop' + - name: Rubocop run + run: | + bash -c " + rubocop --require code_scanning --format CodeScanning::SarifFormatter -o rubocop.sarif + [[ $? -ne 2 ]] + " + - name: Upload Sarif output + uses: github/codeql-action/upload-sarif@v1 + with: + sarif_file: rubocop.sarif diff --git a/codeql/uniform-setup-for-cli-and-vs-code.md b/codeql/uniform-setup-for-cli-and-vs-code.md new file mode 100644 index 0000000..dcca79c --- /dev/null +++ b/codeql/uniform-setup-for-cli-and-vs-code.md @@ -0,0 +1 @@ +An example of a setting up the codeql cli/library/vs code plugins together for version consistency can be found here: https://github.com/hohn/codeql-cli-vscode-setup diff --git a/reporting/advanced-security-reporting.md b/reporting/advanced-security-reporting.md new file mode 100644 index 0000000..2921234 --- /dev/null +++ b/reporting/advanced-security-reporting.md @@ -0,0 +1,22 @@ +# Open Source Reporting Tools + +- Dependabot + - [ ] https://github.com/mr-sherman/get-dependency-alerts-in-org + - [ ] https://github.com/tonycch/get-dependabot-alerts-sample + - [ ] https://github.com/andyfeller/gh-dependency-report + - [ ] https://github.com/thedave42/generate-dependencies-csv-action +- Code scanning + - [ ] https://github.com/jhutchings1/get-code-scanning-alerts-in-org-sample + - [ ] https://github.com/issc29/generate-vuln-report + - [ ] https://github.com/marketplace/actions/get_code_scanning_result + - [ ] https://github.com/marketplace/actions/github-advanced-security-api-to-csv + - [ ] https://github.com/peter-murray/github-security-report-action +- Secret scanning + - [ ] GHES 3.1+: https://github.com/cmboling/get-secret-scanning-alerts-in-org-sample/tree/ghes/base-url-included + - [ ] dotcom/GHEC: https://github.com/cmboling/get-secret-scanning-alerts-in-org-sample +- Other + - [ ] https://github.com/ThibaudLopez/GHAS +- SIEM integrations + - [ ] https://github.blog/2022-10-13-introducing-github-advanced-security-siem-integrations-for-security-professionals/ + - [ ] https://github.blog/2023-03-10-introducing-github-vulnerability-management-integrations-for-security-professionals/ + - [ ] https://resources.github.com/security/integrating-github-advanced-security-with-third-party-platforms/ diff --git a/reporting/ghes-mysql-connect.md b/reporting/ghes-mysql-connect.md new file mode 100644 index 0000000..308adb6 --- /dev/null +++ b/reporting/ghes-mysql-connect.md @@ -0,0 +1,7 @@ +### SQL queries for Advanced Security metrics +Normally you would use the APIs to get this data, use the Security Overview page to review GHAS rollout and/or use the webhooks to sync GHAS related information to Slack or some centralised security platform. +If you're on GHES, you can get into the `ghes-console` and run some SQL queries to get pretty much the same data. + +If at all possible use the available APIs and webhooks to get this data. The method described here is reserved for users who have access to the `ghe-dbconsole` and have the intention of reading/getting information about Advanced Security rollout. + +The syntax to run this on the appliance is `echo ';' | ghe-dbconsole -y` OR run `ghe-dbconsole -y` and a `mysql` prompt will come up for you to run some queries. diff --git a/reporting/issues_csv/README.md b/reporting/issues_csv/README.md new file mode 100644 index 0000000..f6cd215 --- /dev/null +++ b/reporting/issues_csv/README.md @@ -0,0 +1,2 @@ +A `powershell` script that fetches Code Scanning, Secret Scanning and Dependabot alerts for an organization and outputs them to a CSV file using `jq`. +Includes the repository topics that might be used for filtering and grouping the alerts. diff --git a/reporting/issues_csv/code_scanning.jq b/reporting/issues_csv/code_scanning.jq new file mode 100644 index 0000000..5f65042 --- /dev/null +++ b/reporting/issues_csv/code_scanning.jq @@ -0,0 +1,6 @@ +### the csv headers +["repo","severity","created","fixed","dismissed","dismissed reason","state","url","topics"], +(.[]| +### the json path +[.repository.name,.rule.severity,.created_at,.fixed_at,.dismissed_at,.dismissed_reason,.state,.html_url,($topics[][.repository.name]|join(" "))] +) | @csv diff --git a/reporting/issues_csv/dependabot.jq b/reporting/issues_csv/dependabot.jq new file mode 100644 index 0000000..45d7c1b --- /dev/null +++ b/reporting/issues_csv/dependabot.jq @@ -0,0 +1,16 @@ +### the csv headers +["repo","package","severity","CVSS","created","fixed","dismissed","dismissed reason","state","url","topics"], +(.[].data.repository.vulnerabilityAlerts.edges[0].node | select(.!=null)| +### the json path +[.repository.name, + .securityVulnerability.package.name, + .securityVulnerability.severity, + .securityVulnerability.advisory.cvss.score, + .createdAt, + .fixedAt, + .dismissedAt, + .dismissReason, + .state, + ("https://github.com/beazley/"+.repository.name+"/security/dependabot/"+(.number|tostring)), + ($topics[][.repository.name]|join(" "))] +) | @csv diff --git a/reporting/issues_csv/reporting.ps1 b/reporting/issues_csv/reporting.ps1 new file mode 100644 index 0000000..78db83e --- /dev/null +++ b/reporting/issues_csv/reporting.ps1 @@ -0,0 +1,26 @@ +#!/usr/bin/env pwsh +$ORG = "mbaluda-org" + +### FETCH TOPICS ### +$topics = gh api --cache 5m orgs/$ORG/repos -q 'map(select(.name)|{(.name):(.topics)})|add' | jq -s 'add' +$topics | Out-File topics_map.json -encoding utf8 + +### CODE SCANNING ALERTS ### +gh api orgs/$ORG/code-scanning/alerts --method GET --paginate | jq -rf code_scanning.jq --slurpfile topics topics_map.json > code_scanning.csv + +### SECRET SCANNING ALERTS ### +gh api orgs/$ORG/secret-scanning/alerts --method GET --paginate | jq -rf secret_scanning.jq --slurpfile topics topics_map.json > secret_scanning.csv + +### DEPENDABOT SCANNING ALERTS ### +$repos = $topics | jq 'keys[]' +$(foreach ($repo in $repos) { + gh api graphql -F group=$ORG -F repo=$repo -f query=' + query ($endCursor: String, $group: String!, $repo: String!) { + repository(owner: $group, name: $repo) { + vulnerabilityAlerts(first: 100, after: $endCursor) { + edges { node { createdAt fixedAt dismissedAt dismissReason state securityVulnerability { package { name } severity advisory { cvss { score } } } repository { name } number } } + pageInfo { hasNextPage endCursor } + } + } + }' --paginate + }) | jq -srf dependabot.jq --slurpfile topics topics_map.json > dependabot.csv diff --git a/reporting/issues_csv/secret_scanning.jq b/reporting/issues_csv/secret_scanning.jq new file mode 100644 index 0000000..fd6565f --- /dev/null +++ b/reporting/issues_csv/secret_scanning.jq @@ -0,0 +1,6 @@ +### the csv headers +["repo","type","created","fixed","resolution","state","url","topics"], +(.[] | select(.rule.severity!="severity")| +### the json path +[.repository.name,.secret_type,.created_at,.resolved_at,.resolution,.state,.html_url,($topics[][.repository.name]|join(" "))] +) | @csv diff --git a/secret-scanning/user-defined-patterns-considerations.md b/secret-scanning/user-defined-patterns-considerations.md new file mode 100644 index 0000000..69d850d --- /dev/null +++ b/secret-scanning/user-defined-patterns-considerations.md @@ -0,0 +1,16 @@ +- overall cost of scans on push is very low. it does not depend on LOC, only the size of the files. so they have a very small memory footprint unless you are pushing 100 mbs on each push. +backfills/full history scans are more expensive, and are relative to the size of the repo, how well its maintained and how costly it is to run git commands. The load here is always one time when scanning is first enabled. +- We provide configurability on how many scans of either type can be run at a given time. It can speeded up or slowed down to control the load on the system. The specific config names have changed from 3.0. +Some key things that are different: +- backfill scans are no longer capped at 15 mins, we run them till completion. +- some of the defaults for how many backfill scans have changed (previously we used to run 10 every 10 mins, now we pick up 1 backfill job every 10 seconds as long as there isnt another active one in flight).. +- everytime a user defined pattern is created, a backfill is triggered for all the repo(s) under scope. That can add additional load ad hoc. +- You should expect to see more network traffic, particularly when backfills are run. thats because scans are no longer run on the file servers, they are run in their own jobs. For single VM, tahts mostly cross the loopback address, for cluster setups that across the job server and file server nodes. +- no concerns for a 1000 repos that was discussed for Infosys. +- If for this or any other customers we are talking about similar or higher scale but with a high number of active monorepos, i can see a raesonable load during backfills. For reference, i would consider that if you have a 1000 very large mono repos in a isntance with 10s of thousands of repos, that would require a bit more thought. +- Note that in none of the cases above incremental or scan on push is a matter of concern. +- To Control backfill traffic, customers can consider a more gradual rollout of scanning across repos in their orgs/instance. when enabled at the org level, we make an attempt to do so using some of the defaults i described, but rollout gives more control. +for user defined patterns, a gradual rollout via enablement is not an option when its created at the org or enterprise level. I would highly recommend doing extensive testing with a repo for a new user defined pattern with data before applying it broadly. One option here for new customers is to create these first, and then rollout enablement, so that backfills for these are included as part of the backfills that are done at enablement. +- In terms of resources usage + - with controlled backfills and rollout without using user defined patterns, unless the instances are at the seams and have a couple of Gbs of memory available, you will be :thubs: .. + -if the customer is also planning to use user defined patterns excessively (and i mean tens or hhundreds of patterns), you would want to have upto 10-20% more resources than the min, especially when the backfills are being run or user defined patterns are being created. diff --git a/troubleshooting/codeql-builds/compiled-languages-cpp.md b/troubleshooting/codeql-builds/compiled-languages-cpp.md new file mode 100644 index 0000000..c7560d6 --- /dev/null +++ b/troubleshooting/codeql-builds/compiled-languages-cpp.md @@ -0,0 +1,5 @@ +# FAQ + +## Does CodeQL need the resulting object files from the C++ build? + +CodeQL needs to monitor the actual build. Every time we see the build invoke the C++ compiler, we also "compile" the same source code with our own "compiler" that generates what we need for the actual analysis. We don't use the object files from the regular compiler at all. \ No newline at end of file diff --git a/troubleshooting/codeql-builds/compiled-languages-csharp.md b/troubleshooting/codeql-builds/compiled-languages-csharp.md new file mode 100644 index 0000000..d739ce6 --- /dev/null +++ b/troubleshooting/codeql-builds/compiled-languages-csharp.md @@ -0,0 +1,224 @@ +Scanning a C# application with CodeQL + +# Build Failures + +## [error]We were unable to automatically build your code. Please replace the call to the autobuild action with your custom build steps. + +
+Expand for sample workflow failure output + +``` + Exit code 1 + Attempting to locate build script + Error: Could not auto-detect a suitable build method + Error: We were unable to automatically build your code. Please replace the call to the autobuild action with your custom build steps. Failure invoking /opt/hostedtoolcache/CodeQL/0.0.0-20221010/x64/codeql/csharp/tools/autobuild.sh with arguments . + + Exit code 1 and error was: + + Error: Could not auto-detect a suitable build method + + CommandInvocationError: Failure invoking /opt/hostedtoolcache/CodeQL/0.0.0-20221010/x64/codeql/csharp/tools/autobuild.sh with arguments . + + Exit code 1 and error was: + + Error: Could not auto-detect a suitable build method + + at runTool (/home/runner/work/_actions/github/codeql-action/v2/lib/codeql.js:867:15) + at processTicksAndRejections (node:internal/process/task_queues:96:5) + at async Object.runAutobuild (/home/runner/work/_actions/github/codeql-action/v2/lib/codeql.js:559:13) + at async runAutobuild (/home/runner/work/_actions/github/codeql-action/v2/lib/autobuild.js:97:5) + at async run (/home/runner/work/_actions/github/codeql-action/v2/lib/autobuild-action.js:71:17) + at async runWrapper (/home/runner/work/_actions/github/codeql-action/v2/lib/autobuild-action.js:88:9) +``` +
+ + +This error indicates there is a scenario where our [C# AutoBuilder](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-the-codeql-workflow-for-compiled-languages#c) is unable to build your code. No sweat, check out some of the resources below to get you started: + +Ensure your required build tooling is installed your [runner](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources) + - Windows 2019 runner + - [Visual Studio 2019 Enterprise pre-installed](https://github.com/actions/runner-images/blob/main/images/win/Windows2019-Readme.md#visual-studio-enterprise-2019) + - [.NET Framework Developer Pack](https://github.com/actions/runner-images/blob/main/images/win/Windows2019-Readme.md#net-framework) + - [.NET Core SDK](https://github.com/actions/runner-images/blob/main/images/win/Windows2019-Readme.md#net-core-sdk) + - Windows 2022 runner + - [Visual Studio 2022 Enterprise pre-installed](https://github.com/actions/runner-images/blob/main/images/win/Windows2022-Readme.md#visual-studio-enterprise-2022) + - [.NET Framework Developer Pack](https://github.com/actions/runner-images/blob/main/images/win/Windows2022-Readme.md#net-framework) + - [.NET Core SDK](https://github.com/actions/runner-images/blob/main/images/win/Windows2022-Readme.md#net-core-sdk) + + +If any custom tooling is required, consider pulling into your action via [custom script](https://docs.github.com/en/actions/using-github-hosted-runners/customizing-github-hosted-runners) + + +### DotNet (.NET standard / core ) +Using `dotnet` is best documented at: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-net. The [actions/setup-dotnet](https://github.com/actions/setup-dotnet) action can assist in configuring proper build tools. + +#### NuGet Error NU1301 +This can indicate your custom package server is not configured which may fail the `dotnet restore` command. For private package servers, the follwing guidance shows how to add package sources: [Setting up authentication for nuget feeds](https://github.com/actions/setup-dotnet#setting-up-authentication-for-nuget-feeds) + +#### NuGet.targets(132,5): warning : Your request could not be authenticated by the GitHub Packages service. Please ensure your access token is valid and has the appropriate scopes configured. + +The `actions/setup-dotnet` action supports [setting up authentication for nuget feeds](https://github.com/actions/setup-dotnet#setting-up-authentication-for-nuget-feeds). Add this before the `autobuild` / custom build steps in your workflow: +```yml +- uses: actions/setup-dotnet@v3 + with: + source-url: https://nuget.pkg.github.com//index.json + env: + NUGET_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}} +``` + +Alternatively, consider adding auth for your GitHub Packages hosted NuGet feed using the nuget CLI tooling. + +```yml + - name: add nuget auth + run: dotnet nuget add source https://nuget.pkg.github.com//index.json -n "GitHub" -u USERNAME -p "${{ secrets.GH_PACKAGES_READ_ONLY }}" --store-password-in-clear-text + ``` + +### .NET Framework + +#### NuGet Authentication +Utilize the [nuget/setup-nuget](https://github.com/nuget/setup-nuget#basic) action to pass package key/source to nuget exe. + +```yml +- uses: nuget/setup-nuget@v1 + with: + nuget-api-key: ${{ secrets.NuGetAPIKey }} +``` + +#### Manual Build Steps on Windows Runners +NOTE: if you require windows OS to build, ensure you are using a windows runner. + +Example using `windows-latest`: +- Note: The `-latest` runner images are the latest stable images that GitHub provides, and might not be the most recent version of the operating system available from the operating system vendor. +```yml +jobs: + analyze: + name: Analyze + runs-on: windows-latest +``` + +Next, consider specifying your own build steps from an existing CI workflow: +- The [microsoft/setup-msbuild](https://github.com/microsoft/setup-msbuild) and [Nuget/setup-nuget](https://github.com/nuget/setup-nuget) actions are popular tools to assist in this configuration + + +```yml + # Autobuild attempts to build any compiled languages (C/C++, C#, or Java). + # If this step fails, then you should remove it and run the build manually (see below) + #- name: Autobuild + # uses: github/codeql-action/autobuild@v2 + + # Discover where the MSBuild tool is and automatically add it to the PATH environment variable + - name: Setup MSBuild + uses: microsoft/setup-msbuild@v1 + + # Download/installs a given version of NuGet.exe. Using this action will add nuget to your $PATH + - name: Setup NuGet + uses: NuGet/setup-nuget@v1 + + # CI build with best practices from: https://codeql.github.com/docs/codeql-cli/creating-codeql-databases/#specifying-build-commands + - name: .NET Build Steps + run: | + nuget restore .\FullDotNetWebApp.sln -DisableParallelProcessing + msbuild .\FullDotNetWebApp.sln /p:UseSharedCompilation=false /t:rebuild /p:Platform="Any CPU" /p:Configuration="Debug" /p:MvcBuildViews=true + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v2 +``` + +## "You are running out of disk space. The runner will stop working when the machine runs out of disk space." + +Running low on disk using the default Actions runner? + +GitHub also offers larger runners, which are available in larger disk configurations. For more information, see "[About larger runners.](https://docs.github.com/en/actions/using-github-hosted-runners/about-larger-runners#machine-specs-for-larger-runners)" +- See also: [Vertical Scaling](#vertical-scaling---throw-hardware-at-the-software-problem) + +Alternatively, try a few of these workarounds for a potential quick fix: + +Specify the OS Disk's (C:\) temp directory to store the CodeQL database. There is a slower disk speed tradeoff compared to using the Data Disk (D:\) + ```yml +- name: Initialize CodeQL + uses: github/codeql-action/init@v2 + with: + db-location: ‘C:\windows\temp\codeql-database’ +``` + +Clean up large directories of [preinstalled software](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#preinstalled-software) that you are not using on the windows runner OS Disk. Add this to your “CodeQL” workflow: +```yml +- name: Clean up some disks + run: | + rd C:\Android\android-sdk + docker system prune -af +``` + +## MvcBuildViews target failures + +This can manifest through a variety of errors +- `error ASPPARSE` +- `[error]C:\Windows\Microsoft.NET\Framework\v4.0.30319\Config\web.config(113,0): Error ASPCONFIG: Could not load type` +- `Error ASPCONFIG: It is an error to use a section registered as allowDefinition='MachineToApplication' beyond application level.` +- `(AfterBuildCompiler target) -> D:\a\Orchard\Orchard\src\Orchard.Web\Modules\Orchard.Glimpse\web.config(38): error ASPCONFIG: Could not load file or assembly 'System.Web.Mvc, Version=5.2.3, Culture=neutral, PublicKeyToken=31bf3856ad364e35' or one of its dependencies. The located assembly's manifest definition does not match the assembly reference. (Exception from HRESULT: 0x80131040)` + +The CodeQL compiler tracer used for `csharp` will auto inject the /p:MvcBuildViews=true flag. This pre-compilation of Views gives us the ability to extract the generated code from those files, leading to (potentially) better error reporting and location information if a query does flag an issue. The lack of view information passing through CodeQL to the compiler will lead to an incomplete database, where important dataflow sources/sinks/taint-steps are not included in the analysis. + +The recommendation here is to ensure that passing /p:MvcBuildViews=true to your CI build will compile even outside of CodeQL. Having a developer reivew this on their local machine is the best scenario. This can be on done on the specific web project by adding `true` to the local .csproj ( you will often find this defaulted to false). The MVC full framework steps are listed [here](https://learn.microsoft.com/en-us/archive/blogs/jimlamb/turn-on-compile-time-view-checking-for-asp-net-mvc-projects-in-tfs-build-2010). There are a few different reasons why this can cause your project to fail compilation. + +For `Error ASPCONFIG: It is an error to use a section registered as allowDefinition='MachineToApplication' beyond application level.`, change the locations of the obj and publish folder to not be located under the project folder of the website. If you have bin/obj files checked into source then this could be a likely culprit: https://gunnarpeipman.com/aspnet-mvc-allowdefinition-machinetoapplication/. You will find [various permutations of this recommendation](https://stackoverflow.com/questions/12778088/allowdefinition-machinetoapplication-error-setting-mvcbuildviewstrue-mvcbui) out there! + +For `Error ASPCONFIG: Could not load type 'X.Y.Z'`, ensure that you do not have excluded `.cshtml`, `.ashx`, `.ashx.cs`, `.aspx` or `.aspx.cs` files on disk in existing `Views` folders or the Root folder of your project! You can show hidden files in your solution view to hunt these down and remove from these folders. MvcBuildViews does not observe the file include from the csproj when compiling the application. You may have to hunt these down one by one, so adding `true` to your local .csproj may help you get this done on your local machine with Visual Studio. The `Error List` view in Visual Studio will have a column that shows you the actual File name you need to delete. + +# Speed up C# Analysis + +Start here: [CodeQL Docs - The build takes too long](https://docs.github.com/en/enterprise-cloud@latest/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/troubleshooting-the-codeql-workflow#the-build-takes-too-long). + +## Optimization - Caching Dependencies + Depending on the number of dependencies, it may be faster to restore packages for your project using the Actions dependency cache. Projects with many large dependencies should see a performance increase as it cuts down the time required for downloading. Projects with fewer dependencies may not see a significant performance increase and may even see a slight decrease due to how NuGet installs cached dependencies. The performance varies from project to project. See [this article](https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-net#caching-dependencies) for configuring the NuGet dependency cache. + +## Optimization - Removing Code From Scans +CodeQL will extract and analyze any code that is passed through the compiler. Consider excluding any code you do not wish to include in a security scan to speed up and remove noise from this process. This is commonly employed for unit tests, demo code, or code that would not benefit from being scanned (ex: DacPacs). + +With .NET we can employ a few mechanisms to remove code from CodeQL scans (e.g. you would want to run your unit test in another workflow ): +- A [solution filter](https://docs.microsoft.com/en-us/visualstudio/msbuild/solution-filters?view=vs-2019) to only build required projects +- An explicit [solution file that excludes projects](https://docs.microsoft.com/en-us/visualstudio/ide/how-to-exclude-projects-from-a-build?view=vs-2022) + - example from the Open Source project: [Identity Server](https://github.com/DuendeSoftware/IdentityServer/) + - have a [build.sh script wrapper](https://github.com/DuendeSoftware/IdentityServer/blob/main/build/Program.cs#L47) around their solution targets + - distinct [IdentityServer.CodeQL.sln solution](https://github.com/DuendeSoftware/IdentityServer/blob/main/Duende.IdentityServer.CodeQL.sln) excluding unit tests + - [CodeQL yaml passes in a flag to build script](https://github.com/DuendeSoftware/IdentityServer/blob/44d8d5964edfae20c4be424c0b3a2ed5050c6fe9/.github/workflows/codeql-analysis.yml#L57) to use the CodeQL solution +- Build in release mode - exclude test projects from that [build configuration](https://docs.microsoft.com/en-us/previous-versions/visualstudio/visual-studio-2015/ide/how-to-create-and-edit-configurations?view=vs-2015&redirectedfrom=MSDN#to-modify-a-solution-wide-build-configuration) + +## Optimizations - CodeQL Queries +- Tweak your current codeql yml workflow in a few ways: + - remove security-extended queries, the default query pack with smaller set of queries will complete faster + - As of [v2.10.5](https://github.com/github/codeql-action/releases/tag/codeql-bundle-20220908) - Query Suite Counts + - code-scanning (default) - 49 queries + - security-extended - 66 queries + - security-and-quality - 171 queries + +- Micro Optimizations: Consider these as a potential quick hit to resolve a specific problem + - Review workflow log timings to identify a any query that is taking a long time you can consider excluding it via a [CodeQL-config file](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-a-custom-configuration-file) + - add a [query-filter](https://github.blog/changelog/2022-08-31-code-scanning-customize-your-codeql-analysis-using-query-filters/) to [exclude a specific query from analysis](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#excluding-specific-queries-from-analysis) + + - tweak the way CodeQL allocates memory to possibly make the workflow succeed in low memory conditions (for example, just below the runs-on field): [see sample](https://github.com/vulna-felickz/FullDotNetWebApp/pull/8/commits/263bbc8816a964d70f6267f6b6717f56b6bf6a1d) + ```yml + env: + CODEQL_ACTION_EXTRA_OPTIONS: '{"database": {"run-queries": ["--off-heap-ram=0"]}}' + ``` + + - CodeQL will (by default) pull in source code from your dependencies using CIL extraction to assist in mapping out your data flows. While this can drastically improve the precision of the results, this can also lead to a large increase in database size. You might consider disabling this feature for a quick scan but running a cron based scan with the option enabled. + ```yml + env: + CODEQL_EXTRACTOR_CSHARP_OPTION_CIL: false + ``` + + +## Vertical Scaling - Throw hardware at the software problem. + +Large applications can be compute/memory/disk bound as the base Actions runners are small instances (2core/8GBram/14GB SSD). See the [recommended hardware requirements for CodeQL](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/recommended-hardware-resources-for-running-codeql) based on Codebase size. +- Setup a [self-hosted CI action runner](https://docs.github.com/en/enterprise-cloud@latest/actions/hosting-your-own-runners/adding-self-hosted-runners#adding-a-self-hosted-runner-to-an-organization) in your infrastructure that has some more powerful specs that can handle your large application. +- [Actions larger runners ](https://docs.github.com/en/actions/using-github-hosted-runners/using-larger-runners) + - This allows for up to a 64 core machine with 256GB RAM and 2040 GB of SSD storage + + +## Horizontal Scaling - Continue to decompose your solution. + +Making an investment in optimizing your build process can drastically speed up your developer experience, CI pipelines and start the process of "decomposing the monolith". Continued investment in large or legacy applications is important to keep your security posture and dependencies up to date. Review the suggestions for [using domain-driven design to modernize your monolithic application](https://learn.microsoft.com/en-us/azure/architecture/microservices/migrate-monolith). If you have already investigated removing projects from your solutions that you do not wish to expose to a security scan (test projects / demo code), then you have already begun this journey. + +A great use case would be to filter separate solutions by front end (ex: Web.sln) and back end code(ex: API.sln) that are separated by process/network boundaries. CodeQL can detect data flows through the code but once it reaches a process boundary the flow is stopped. This creates a natural separation point for both feature development teams and security scans based data flows. This would further enable a decrease in wall-clock scan time by using parallel per-solution scans using an [Actions matrix strategy](https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs) (such that each gets its own runtime and resources). It will be important to include your common framework code in each solution so that you get a successful compilation while you further analyze other ways to share code. diff --git a/troubleshooting/codeql-builds/compiled-languages-go.md b/troubleshooting/codeql-builds/compiled-languages-go.md new file mode 100644 index 0000000..b27630b --- /dev/null +++ b/troubleshooting/codeql-builds/compiled-languages-go.md @@ -0,0 +1,40 @@ +## GoLang Private Modules + +Autobuild fails with error "Some packages could not be found" + +There are two options when it comes to private repositories: + +- Set-up the Go environment within the Actions workflow (not vendoring then) +- Vendor the dependencies + +Setting up the Go environment can be done by adding a Actions step to update the [Go settings](https://go.dev/ref/mod#private-modules) pointing them to use a [GitHub Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with the corresponding access to the private repository. +The example below shows how this can be done using a single step beforet the CodeQL Initize step and stores the GitHub PAT in Secrets. + +**Example:** + +```yml +name: CodeQL + +env: + GOLANG_TOKEN: ${{ secrets.GOLANG_GITHUB_TOKEN }} + GOLANG_USER: octocat + +# ... +jobs: + analyze: + name: Analyze + # ... + steps: + - name: Go Configuration + run: git config --global url."https://${GOLANG_USER}:${GOLANG_TOKEN}@github.com".insteadOf "https://github.com" + + # ... Start scanning +``` + +Alternatively, pass the token into the CodeQL init action to allow it to be used for downstream git operations: + +```yml +- uses: github/codeql-action/init@v2 + with: + external-repository-token: ${{ secrets.GOLANG_GITHUB_TOKEN }} +``` diff --git a/troubleshooting/codeql-builds/compiled-languages-java.md b/troubleshooting/codeql-builds/compiled-languages-java.md new file mode 100644 index 0000000..6f141ac --- /dev/null +++ b/troubleshooting/codeql-builds/compiled-languages-java.md @@ -0,0 +1,71 @@ + +# Private Package Registries + +## The autobuild for java is failing when running Maven build command and a private package registry is needed - `status: 401 Unauthorized ` +- ex: artifactory where our pom.xml dependencies are stored + +Assuming the given package registry instance is publicly accessible and needs credentials: + +Option 1 - Pass credentials via environment variable from Actions secrets and configure Maven settings to utilize those credentials (see sample [here](https://github.com/actions/setup-java/blob/main/docs/advanced-usage.md#yaml-example)) + +ex `workflow.yml` step: +```yml + env: + MAVEN_USERNAME: maven_username123 + MAVEN_CENTRAL_TOKEN: ${{ secrets.MAVEN_CENTRAL_TOKEN }} +``` + +ex `settings.xml` +```xml + + maven + ${env.MAVEN_USERNAME} + ${env.MAVEN_CENTRAL_TOKEN} + +``` + +Option 2 - Use the GitHub https://github.com/actions/setup-java#maven-options action to generate maven's settings.xml on the fly and pass the values to Apache Maven GPG Plugin as well as Apache Maven Toolchains. + +```yml + - name: Set up Apache Maven Central + uses: actions/setup-java@v3 + with: + distribution: 'temurin' + java-version: '11' + server-id: maven # Value of the distributionManagement/repository/id field of the pom.xml + server-username: MAVEN_USERNAME # env variable for username in deploy + server-password: MAVEN_CENTRAL_TOKEN # env variable for token in deploy + ``` + +Option 3 - Use the [maven-settings-action](https://github.com/s4u/maven-settings-action) to dynamically create/overrite a `settings.xml` that contains the credentials for your specified package manager. + +```yml +- if: matrix.language == 'java' + name: Configure maven credentials + uses: s4u/maven-settings-action@v2.6.0 + with: + servers: '[{"id": "central", "username": "${{ secrets.MAVEN_USERNAME }}", "password": "${{ secrets.MAVEN_CENTRAL_TOKEN }}"}]' +``` + +See also: [401 due to private package server configuration](compiled-languages.md#401-due-to-private-package-server-configuration) + +# Build Failures + +## java.lang.IllegalArgumentException: Unsupported class file major version ## + +Ensure you are compiling your java application using CodeQL tracing on a supported version of the JDK as found here: https://codeql.github.com/docs/codeql-overview/supported-languages-and-frameworks/ + +## Fatal error compiling: error: invalid target release: \## + +Alternative error: +``` +> error: invalid source release: +``` + +Resolution here is to specify your [desired java version via the setup-java action](https://github.com/actions/setup-java#supported-version-syntax) +```yml +- uses: actions/setup-java@v3 + with: + java-version: 17 + distribution: 'microsoft' +``` diff --git a/troubleshooting/codeql-builds/compiled-languages.md b/troubleshooting/codeql-builds/compiled-languages.md new file mode 100644 index 0000000..7838bba --- /dev/null +++ b/troubleshooting/codeql-builds/compiled-languages.md @@ -0,0 +1,71 @@ +# Scanning a compiled language with CodeQL +* NOTE: This guide will focus on GitHub Actions but the concepts can be applied to the CodeQL CLI on other CI platforms. + +## Language Specific Guidance +* [CSharp](compiled-languages-csharp.md) +* [C++](compiled-languages-cpp.md) +* [Java](compiled-languages-java.md) +* [Go](compiled-languages-go.md) + +## Autobuilder +The autobuilder action (see [docs](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-the-codeql-workflow-for-compiled-languages#about-autobuild-for-codeql) ) + +## Build Customizations +See common build configuration and specific compiler flags: [specifying build commands](https://codeql.github.com/docs/codeql-cli/creating-codeql-databases/#specifying-build-commands) + +## Common Problems + +### Autobuilder [error]We were unable to automatically build your code. Please replace the call to the autobuild action with your custom build steps. + +See [language specific guidance](#language-specific-guidance) for common resolutions to add custom build steps + + +### 401 due to private package server configuration + +Ensure network access from GitHub runners to your private registry is open + - For IP Whitelisting, consider using [Larger Runners with Static IP](https://docs.github.com/en/actions/using-github-hosted-runners/using-larger-runners#networking-for-larger-runners) + - See Also: [Connecting Actions to a private network](https://docs.github.com/en/actions/using-github-hosted-runners/connecting-to-a-private-network) + - Alternatively, consider a self-hosted actions runner that will execute within your existing private network. See ["Hosting your own runners"](https://docs.github.com/en/actions/hosting-your-own-runners) + +See [language specific guidance](#language-specific-guidance) for authentication options to popular package mangers + +### Out of Memory +ex: + +> 2022-06-01T20:08:13.6909315Z Exit code 137 and error was: + +>A fatal error occurred: RelationManager failed to produce already COMPUTED FlowSummaryImpl#b68d378d::Private::TConsSummaryComponentStack#fff/3@e38197wv + + +These errors typically indicate that your project is too large for CodeQL to analyse with the amount of RAM found on the default GitHub runners. You can tweak the way we allocate memory to possibly make the workflow succeed by adding the following environment variable to your CodeQL job (for example, just below the runs-on field): + + +We can tweak the way CodeQL allocates memory to possibly make the workflow succeed +```yml + env: + CODEQL_ACTION_EXTRA_OPTIONS: '{"database": {"run-queries": ["--off-heap-ram=0"]}}' +``` +alternatively we can further define limits +```yml + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v2 + with: + # Increase Values seen in logs: + #2022-06-01T19:37:19.0200037Z CODEQL_RAM: 119741 + #2022-06-01T19:37:19.0200307Z CODEQL_THREADS: 32 + ram: 64000 + threads: 16 +``` + +## Reviewing Results + +Helpful Articles to understand how to review, troubleshoot, and debug logs: + +- [Viewing Code Scanning Logs](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/viewing-code-scanning-logs) +- [Workflow verbose logging in debug mode](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/troubleshooting-the-codeql-workflow#creating-codeql-debugging-artifacts) +- [Adding artifacts on every CodeQL Run](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/troubleshooting-the-codeql-workflow#creating-codeql-debugging-artifacts-using-a-workflow-flag) +- [Exit Codes](https://codeql.github.com/docs/codeql-cli/exit-codes/) + + +## Optimizations +- CodeQL Docs - [The build takes too long](https://docs.github.com/en/enterprise-cloud@latest/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/troubleshooting-the-codeql-workflow) diff --git a/troubleshooting/codeql-builds/interpreted-languages-python.md b/troubleshooting/codeql-builds/interpreted-languages-python.md new file mode 100644 index 0000000..6f9b30e --- /dev/null +++ b/troubleshooting/codeql-builds/interpreted-languages-python.md @@ -0,0 +1,37 @@ +# Build Failures + +## ERROR: In --require-hashes mode, all requirements must have their versions pinned with ==. + +Error/Warning in the workflow logs like: + +```yml +ERROR: In --require-hashes mode, all requirements must have their versions pinned with ==. These do not: + importlib-metadata from https://files.pythonhosted.org/packages/b5/64/ef29a63cf08f047bb7fb22ab0f1f774b87eed0bb46d067a5a524798a4af8/importlib_metadata-5.0.0-py3-none-any.whl (from alembic==1.8.1->-r requirements.txt (line ###)) +package installation with `pip install -r requirements.txt` failed, see error above +##[endgroup] +##[warning]An error occurred while trying to automatically install Python dependencies: Error: The process '/usr/bin/python3' failed with exit code 1 +Please make sure any necessary dependencies are installed before calling the codeql-action/analyze step, and add a 'setup-python-dependencies: false' argument to this step to disable our automatic dependency installation and avoid this warning. +``` +![image](https://user-images.githubusercontent.com/1760475/198150549-61326671-e7cc-4cbc-b640-4858fe294f93.png) + + +This is likely due to a python/pypi/pip version mismatch. Ensure you configure your proper version required to build via [actions/setup-python](https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md#using-the-python-version-input) +- see [stackoverflow](https://stackoverflow.com/a/72980455/343347) + +To resolve, specify your required versions before the codeql-action/init step: +```yml +#Set python version +- uses: actions/setup-python@v4 + with: + python-version: '3.9' + cache: 'pip' # caching pip dependencies +#Downgrade to specific pip version +-run: python -m pip install pip==22.0.4 +``` + +Alternatively, you can disable the auto-install dependency functionality. You will need to configure the build requirements/commands from your existing CI. Specify that codeql should disable the python automatic package restoration and run the CI tooling / commands directly before the analysis step as shown [here](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#analyzing-python-dependencies). +```yml + # Override the default behavior so that the action doesn't attempt + # to auto-install Python dependencies + setup-python-dependencies: false +``` \ No newline at end of file diff --git a/troubleshooting/codeql-builds/interpreted-languages.md b/troubleshooting/codeql-builds/interpreted-languages.md new file mode 100644 index 0000000..2ee96e0 --- /dev/null +++ b/troubleshooting/codeql-builds/interpreted-languages.md @@ -0,0 +1,68 @@ +# Scanning an interpreted language with CodeQL +* NOTE: This guide will focus on GitHub Actions but the concepts can be applied to the CodeQL CLI on other CI platforms. + +## Language Specific Guidance +* [Python](interpreted-languages-python.md) + + +# Troubleshooting + +## [ERROR] Spawned process exited abnormally (code 1; tried to run: [/opt/hostedtoolcache/CodeQL//x64/codeql/javascript/tools/autobuild.sh]) + +This is the higher level error handler for the autobuilder (in this case javascript) + +``` +[ERROR] Spawned process exited abnormally (code 1; tried to run: [/opt/hostedtoolcache/CodeQL/0.0.0-20220401/x64/codeql/javascript/tools/autobuild.sh]) + A fatal error occurred: Exit status 1 from command: [/opt/hostedtoolcache/CodeQL/0.0.0-20220401/x64/codeql/javascript/tools/autobuild.sh] + Error: The process '/opt/hostedtoolcache/CodeQL/0.0.0-20220401/x64/codeql/codeql' failed with exit code 2 + Error: The process '/opt/hostedtoolcache/CodeQL/0.0.0-20220401/x64/codeql/codeql' failed with exit code 2 + at toolrunnerErrorCatcher (/home/runner/work/_actions/github/codeql-action/v2/lib/toolrunner-error-catcher.js:86:19) + at processTicksAndRejections (node:internal/process/task_queues:96:5) + at async Object.extractScannedLanguage (/home/runner/work/_actions/github/codeql-action/v2/lib/codeql.js:519:13) + at async createdDBForScannedLanguages (/home/runner/work/_actions/github/codeql-action/v2/lib/analyze.js:79:13) + at async finalizeDatabaseCreation (/home/runner/work/_actions/github/codeql-action/v2/lib/analyze.js:96:5) + at async runFinalize (/home/runner/work/_actions/github/codeql-action/v2/lib/analyze.js:259:5) + at async run (/home/runner/work/_actions/github/codeql-action/v2/lib/analyze-action.js:78:9) + at async runWrapper (/home/runner/work/_actions/github/codeql-action/v2/lib/analyze-action.js:212:9) +``` + +In your logs, look for an exception with the output `[build-stderr]` + +## [build-stderr] java.lang.OutOfMemoryError: Java heap space +``` +[build-stderr] Exception while extracting /home/runner/work/path/to/file/myfile.js. +[build-stderr] java.lang.OutOfMemoryError: Java heap space +[build-stderr] at java.base/java.util.HashMap.resize(Unknown Source) +[build-stderr] at java.base/java.util.HashMap.putVal(Unknown Source) +[build-stderr] at java.base/java.util.HashMap.put(Unknown Source) +[build-stderr] at java.base/java.util.HashSet.add(Unknown Source) +[build-stderr] at com.semmle.js.extractor.LocationManager.emitLocationsDefault(LocationManager.java:156) +[build-stderr] at com.semmle.js.extractor.LocationManager.emitFileLocation(LocationManager.java:146) +[build-stderr] at com.semmle.js.extractor.LocationManager.emitSnippetLocation(LocationManager.java:141) +[build-stderr] at com.semmle.js.extractor.LocationManager.emitNodeLocation(LocationManager.java:126) +[build-stderr] at com.semmle.js.extractor.LexicalExtractor.extractTokens(LexicalExtractor.java:166) +[build-stderr] at com.semmle.js.extractor.JSExtractor.extract(JSExtractor.java:113) +[build-stderr] at com.semmle.js.extractor.JSExtractor.extract(JSExtractor.java:59) +[build-stderr] at com.semmle.js.extractor.ScriptExtractor.extract(ScriptExtractor.java:85) +[build-stderr] at com.semmle.js.extractor.FileExtractor.extractContents(FileExtractor.java:545) +[build-stderr] at com.semmle.js.extractor.FileExtractor.extract(FileExtractor.java:452) +[build-stderr] at com.semmle.js.extractor.AutoBuild.doExtract(AutoBuild.java:1122) +[build-stderr] at com.semmle.js.extractor.AutoBuild.lambda$extract$8(AutoBuild.java:1106) +[build-stderr] at com.semmle.js.extractor.AutoBuild$$Lambda$29/0x00000008000d4950.run(Unknown Source) +[build-stderr] at java.base/java.util.concurrent.CompletableFuture$AsyncRun.run(Unknown Source) +[build-stderr] at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(Unknown Source) +[build-stderr] at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(Unknown Source) +[build-stderr] at java.base/java.lang.Thread.run(Unknown Source) +``` + +It is best to use the [paths-ignore](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#specifying-directories-to-scan) feature to exclude the file opencv.js. It would look something like this: + +```yml +paths-ignore: + - '**/myfile.js' +``` + +In general, when a repository contains a huge JS file that is output of a compiler/bundler process, it is best to exclude it. As an example: opencv.js is from the OpenCV project, it which case it is the result of translating some C++ code to JS using Emscripten. This source code is unreadable and it wouldn't be helpful to get code scanning alerts in such files anyway. + +References: +- https://github.com/github/codeql/issues/9056#issuecomment-1120793848 \ No newline at end of file diff --git a/troubleshooting/sarif-upload/troubleshooting.md b/troubleshooting/sarif-upload/troubleshooting.md new file mode 100644 index 0000000..7c30f8e --- /dev/null +++ b/troubleshooting/sarif-upload/troubleshooting.md @@ -0,0 +1,95 @@ +## SARIF Upload Errors +* Test environment - GHES 3.2.1 + CodeQL CLI 2.7.2 + +:gift: wrong ref: +``` +codeql github upload-results --github-url=https://cmboling-0bd0debab4ff16db0.ghe-test.ninja/ --sarif=results.sarif --ref=ref/heads/main --commit=5f538e43c27e91cd3e31c5a12b136b69d61a744f --repository=santa-foss/jubilant-octo-pancake --github-auth-stdin=ghp_somethingsomethingsomething +A fatal error occurred: Error uploading SARIF to 'https://cmboling-0bd0debab4ff16db0.ghe-test.ninja/api/v3/repos/santa-foss/jubilant-octo-pancake/code-scanning/sarifs' from '/Users/cmboling/Desktop/jubilant-octo-pancake/results.sarif'. REASON: HTTP/1.1 422 Unprocessable Entity:::{"message":"Invalid request.\n\nref/heads/main does not match /^refs\\/(heads|pull|tags)\\/.*$/.","documentation_url":"https://docs.github.com/enterprise/3.2/rest/reference/code-scanning#upload-a-sarif-file"} +``` + +:santa: bad credentials: +``` +codeql github upload-results --github-url=https://cmboling-0bd0debab4ff16db0.ghe-test.ninja/ --sarif=results.sarif --ref=refs/heads/main --commit=5f538e43c27e91cd3e31c5a12b136b69d61a744f --repository=santa-foss/jubilant-octo-pancake --github-auth-stdin=ghp_somethingsomethingsomethin +A fatal error occurred: Error uploading SARIF to 'https://cmboling-0bd0debab4ff16db0.ghe-test.ninja/api/v3/repos/santa-foss/jubilant-octo-pancake/code-scanning/sarifs' from '/Users/cmboling/Desktop/jubilant-octo-pancake/results.sarif'. REASON: HTTP/1.1 401 Unauthorized:::{"message":"Bad credentials","documentation_url":"https://docs.github.com/enterprise/3.2/rest"} +``` + +:gift: missing token: +``` +codeql github upload-results --github-url=https://cmboling-0bd0debab4ff16db0.ghe-test.ninja/ --sarif=results.sarif --ref=refs/heads/main --commit=5f538e43c27e91cd3e31c5a12b136b69d61a744f --repository=santa-foss/jubilant-octo-pancake +A fatal error occurred: A GitHub token is required to upload SARIF results but none was specified. +(eventual cause: MissingTokenException "An operation was attempted that requires a GitHub token but one could not be fou..." +``` + +:santa: misspelled repo name: +``` +codeql github upload-results --github-url=https://cmboling-0bd0debab4ff16db0.ghe-test.ninja/ --sarif=results.sarif --ref=refs/heads/main --commit=5f538e43c27e91cd3e31c5a12b136b69d61a744f --repository=santa-foss/jubilant-octo-pancak --github-auth-stdin=ghp_somethingsomethingsomething +A fatal error occurred: Error uploading SARIF to 'https://cmboling-0bd0debab4ff16db0.ghe-test.ninja/api/v3/repos/santa-foss/jubilant-octo-pancak/code-scanning/sarifs' from '/Users/cmboling/Desktop/jubilant-octo-pancake/results.sarif'. REASON: HTTP/1.1 404 Not Found:::{"message":"Not Found","documentation_url":"https://docs.github.com/enterprise/3.2/rest/reference/code-scanning#upload-a-sarif-file"} +``` + +:gift: bad token (no security event scope): +``` +codeql github upload-results --github-url=https://cmboling-0bd0debab4ff16db0.ghe-test.ninja/ --sarif=results.sarif --ref=refs/heads/main --commit=5f538e43c27e91cd3e31c5a12b136b69d61a744f --repository=santa-foss/jubilant-octo-pancake --github-auth-stdin=ghp_falalalala +A fatal error occurred: Error uploading SARIF to 'https://cmboling-0bd0debab4ff16db0.ghe-test.ninja/api/v3/repos/santa-foss/jubilant-octo-pancake/code-scanning/sarifs' from '/Users/cmboling/Desktop/jubilant-octo-pancake/results.sarif'. REASON: HTTP/1.1 403 Forbidden:::{"message":"You are not authorized to write security events.","documentation_url":"https://docs.github.com/enterprise/3.2/rest/reference/code-scanning#upload-a-sarif-file"} +``` + +:santa: GHAS not enabled but have a valid token: +``` +codeql github upload-results --github-url=https://cmboling-0bd0debab4ff16db0.ghe-test.ninja/ --sarif=results.sarif --ref=refs/heads/main --commit=5f538e43c27e91cd3e31c5a12b136b69d61a744f --repository=santa-foss/jubilant-octo-pancake --github-auth-stdin=ghp_somethingsomethingsomething +A fatal error occurred: Error uploading SARIF to 'https://cmboling-0bd0debab4ff16db0.ghe-test.ninja/api/v3/repos/santa-foss/jubilant-octo-pancake/code-scanning/sarifs' from '/Users/cmboling/Desktop/jubilant-octo-pancake/results.sarif'. REASON: HTTP/1.1 403 Forbidden:::{"message":"Advanced Security must be enabled for this repository to use code scanning.","documentation_url":"https://docs.github.com/enterprise/3.2/rest/reference/code-scanning#upload-a-sarif-file"} +``` + +:gift: posting SARIF to the wrong repo (where GHAS isn’t enabled): +``` +codeql github upload-results --github-url=https://cmboling-0bd0debab4ff16db0.ghe-test.ninja/ --sarif=results.sarif --ref=refs/heads/main --commit=5f538e43c27e91cd3e31c5a12b136b69d61a744f --repository=santa-foss/fluffy-potato --github-auth-stdin=ghp_somethingsomethingsomething +A fatal error occurred: Error uploading SARIF to 'https://cmboling-0bd0debab4ff16db0.ghe-test.ninja/api/v3/repos/santa-foss/fluffy-potato/code-scanning/sarifs' from '/Users/cmboling/Desktop/jubilant-octo-pancake/results.sarif'. REASON: HTTP/1.1 403 Forbidden:::{"message":"Advanced Security must be enabled for this repository to use code scanning.","documentation_url":"https://docs.github.com/enterprise/3.2/rest/reference/code-scanning#upload-a-sarif-file"} +``` + +:gift: posting SARIF when the SSL certificate is not trusted: +```dotnetcli +curl \ + -X POST \ + -k \ + -H "Accept: application/vnd.github+json" \ + -H "Authorization: Bearer "\ + -H "X-GitHub-Api-Version: 2022-11-28" \ + https://api.github.com/repos/OWNER/REPO/code-scanning/sarifs \ + -d '{"commit_sha":"","ref":"refs/heads/master","sarif":""}' +``` +More information on the API can be found [here](https://docs.github.com/en/rest/code-scanning?apiVersion=2022-11-28#upload-an-analysis-as-sarif-data) + +### Test environments +- GHES 3.2.1 + CodeQL CLI 2.7.2 +======= +## SARIF Parsing Errors + +### Code Scanning could not process the submitted SARIF file: rejecting SARIF, as there are more runs than allowed (123 > 15) +The GitHub api for accepting SARIF uploads has a limiter to prevent that number from being greater than specified (>15) for each upload. + +See limits for various thresholds on the [REST API documentation](https://docs.github.com/en/rest/code-scanning?apiVersion=2022-11-28#upload-an-analysis-as-sarif-data) +* Runs per file +* Results per run +* Rules per run +* Tool extensions per run +* Thread Flow Locations per result +* Location per result +* Tags per rule + +### A fatal error occurred: SARIF file is too large. The GitHub code scanning API accepts a max file size of 2000MB. This file is xxxxMB. File: "xyz.sarif" +- aleternatively - `failed decompressing file from the path: "upload /xyz.sarif.gz": maximum SARIF size exceeded` + +First, review recommendedations per language to reduce the amount of code being scanned (e.g. removing test or demo code from the scan in an attempt to remove unwanted detections from SARIF). A detailed analysis of the SARIF file may indicate a massive number of a single rule, in this case [excluding a specific rule from the analysis](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/customizing-code-scanning#excluding-specific-queries-from-analysis) would be the best solution. Alternatively, use a tool like [filter-sarif action](https://github.com/advanced-security/filter-sarif) to rewrite the SARIF file to exclude specific detections via an exclusion pattern. + +If there are many deep code paths highlighted in the SARIF, use `--max-path=0` (or 1) passed into the analyze step or `database analyze` cli command to get rid of the dataflow paths and reduce the SARIF size that way (NOTE this will impact all rules). + +```yml +- name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v2 + env: + CODEQL_ACTION_EXTRA_OPTIONS: '{"database":{"interpret-results":["--max-paths", 1]}}' +``` + +## Tools to rewrite SARIF +- `jq` +- [Microsoft's SARIF tool](https://github.com/microsoft/sarif-sdk/blob/main/docs/multitool-usage.md) +- [Dr. House's SARIF CLI](https://github.com/hohn/sarif-cli) +- [advanced-security/filter-sarif action](https://github.com/advanced-security/filter-sarif)