Docs/update code sec docs and workflow

README.md

@@ -1 +1,21 @@
-This repo requires pre-commit hooks installed. See the [instructions](https://github.com/uktrade/github-standards/blob/main/README.md#usage) for information of how to install these
+# uktrade/.github
+
+This is the [`.github` repository](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file) for the [`uktrade`](https://github.com/uktrade) organisation. It holds organisation-wide defaults that GitHub applies automatically to any `uktrade` repository that does not define its own.
+
+## What's here
+
+| Path | Purpose |
+|---|---|
+| [`SECURITY.md`](SECURITY.md) | DBT GitHub Security Policy — inherited by every repository without its own `SECURITY.md` |
+| [`.github/pull_request_template.md`](.github/pull_request_template.md) | Default pull request template |
+| [`templates/SECURITY_CHECKLIST.md`](templates/SECURITY_CHECKLIST.md) | Security checklist to copy into a repository root |
+| [`workflow-templates/`](workflow-templates/) | Organisation [workflow templates](https://docs.github.com/en/actions/using-workflows/creating-starter-workflows-for-your-organization) offered when creating a new Action |
+| [`docs/`](docs/) | Step-by-step setup guides referenced from the security policy |
+
+## Contributing
+
+Changes here affect every `uktrade` repository, so raise a PR against this repo rather than copying files elsewhere.
+
+This repo requires the organisation-approved pre-commit hooks. See the [github-standards instructions](https://github.com/uktrade/github-standards/blob/main/README.md#usage) to install them.
+
+The code security diagram (`assets/code_sec_workflow.excalidraw.svg`) is an SVG with the [Excalidraw](https://excalidraw.com/) scene embedded inside it, so it renders as a plain image in `SECURITY.md` while staying editable. Edit it with the [Excalidraw VS Code extension](https://marketplace.visualstudio.com/items?itemName=pomdtr.excalidraw-editor), which reads and writes the embedded scene directly.

docs/codeql-advanced-setup.md

@@ -0,0 +1,11 @@
+# Setting Up Advanced CodeQL for Fork-Based PRs
+
+These instructions support the [CodeQL for Fork-Based PRs](https://github.com/uktrade/.github/blob/main/SECURITY.md#codeql-for-fork-based-prs-optional) control in the DBT GitHub Security Policy. Switching to [**Advanced** CodeQL](https://docs.github.com/en/code-security/how-tos/find-and-fix-code-vulnerabilities/configure-code-scanning/configuring-advanced-setup-for-code-scanning) generates a `codeql.yml` workflow:
+
+1. Navigate to **Settings → Advanced Security** in your repository
+1. Scroll down to the **Code scanning** section; under the **Tools** sub-section there will be an item for CodeQL analysis
+1. Click the **...** button next to the **Default** setup text, then choose **Switch to advanced** from the menu
+1. On the popup, click the **Disable CodeQL** button. This only disables the *default* CodeQL setup — a branch protection rule remains in place that blocks PRs unless a CodeQL scan is detected, so PRs still cannot be merged without the advanced workflow you create in the next step
+1. GitHub will then open its online editor to create a new file called `codeql.yml`, prefilled with the languages CodeQL has detected in your repository. You can modify the contents of this file if needed, however you must leave the workflow name as `CodeQL Advanced`
+1. Once happy with the workflow file contents, click the green **Commit changes** button to trigger a PR to merge this into the default branch
+1. Approve and merge the PR with this workflow file. Once merged, CodeQL will perform an initial scan that can take a while; you can track the progress in the **Actions** tab for your repository

docs/github-security-configuration.md

@@ -0,0 +1,11 @@
+# Applying the DBT GitHub Security Configuration
+
+These instructions support the [GitHub Security Configuration](https://github.com/uktrade/.github/blob/main/SECURITY.md#github-security-configuration) control in the DBT GitHub Security Policy.
+
+**You must be an organisation administrator to apply this configuration**
+
+1. As an organisation administrator, navigate to the [security configurations page](https://github.com/organizations/uktrade/settings/security_products)
+1. Scroll down to the **Apply configurations** section, and enter the name of the repository to be made public in the filter input field
+1. Use the checkbox next to the results list to select all repositories being made public, then use the **Apply configuration** button to select the **Default DBT security** configuration
+1. A confirmation modal will appear displaying a summary of the action being made. Click the **Apply** button
+1. To confirm the configuration has been applied, navigate to **Settings → Advanced Security** in the repository. At the top of the page there should be a banner message **Modifications to some settings have been blocked by organization administrators**

templates/SECURITY_CHECKLIST.md

@@ -0,0 +1,33 @@
+# Security Checklist
+
+Work through this checklist from top to bottom, ticking each item once you have confirmed it is true. Each item links to detailed guidance in the [DBT GitHub Security Policy](https://github.com/uktrade/.github/blob/main/SECURITY.md).
+
+Last checked against the policy: _add date_
+
+## 1. Contributor controls
+
+Actions each contributor takes for themselves, so everyone knows what the controls are and why they exist.
+
+- [ ] [All internal contributors have read the DBT GitHub Security Policy](https://github.com/uktrade/.github/blob/main/SECURITY.md)
+- [ ] [All internal contributors have completed code security training in the last year](https://github.com/uktrade/.github/blob/main/SECURITY.md#security-training)
+- [ ] [All internal contributors have reviewed the GitHub Safety Tips on coding in the open](https://github.com/uktrade/.github/blob/main/SECURITY.md#github-safety-tips)
+
+## 2. Repository-level controls
+
+Defences set up within the repository itself.
+
+- [ ] [A `.pre-commit-config.yaml` file exists so the organisation-approved hooks run before commits](https://github.com/uktrade/.github/blob/main/SECURITY.md#pre-commit-hooks)
+- [ ] [Repository access has been reviewed](https://github.com/uktrade/.github/blob/main/SECURITY.md#repository-access)
+- [ ] [A `CODEOWNERS` file exists so the right people review changes](https://github.com/uktrade/.github/blob/main/SECURITY.md#codeowners)
+- [ ] [The pull request template reminds reviewers to check for secrets](https://github.com/uktrade/.github/blob/main/SECURITY.md#pull-request-template)
+- [ ] [The mandatory custom GitHub properties are set](https://github.com/uktrade/.github/blob/main/SECURITY.md#custom-github-properties)
+- [ ] [Advanced CodeQL is set up if the repository accepts PRs from forks (optional)](https://github.com/uktrade/.github/blob/main/SECURITY.md#codeql-for-fork-based-prs-optional)
+
+## 3. Organisation-applied controls
+
+Controls applied by an organisation administrator and verified by a repository administrator.
+
+- [ ] [The DBT GitHub security configuration is applied to the repository](https://github.com/uktrade/.github/blob/main/SECURITY.md#github-security-configuration)
+- [ ] [Branch protection rules apply to the default branch](https://github.com/uktrade/.github/blob/main/SECURITY.md#branch-protection-rules)
+- [ ] [GitHub Secret Protection is enabled and blocking secrets](https://github.com/uktrade/.github/blob/main/SECURITY.md#github-secret-protection)
+- [ ] [The relevant vulnerability scans are active](https://github.com/uktrade/.github/blob/main/SECURITY.md#vulnerability-scanning)