Add GitHub Advanced Security guide (#134)

Author: johnwatson484

docs/README.md

@@ -81,6 +81,7 @@ These guides provide additional support for meeting and working with the standar
 - [Choosing packages](./guides/choosing_packages.md)
 - [Developer workflows](./guides/developer_workflows.md)
 - [Docker guidance](./guides/docker_guidance.md)
+- [GitHub Advanced Security](./guides/github_advanced_security.md)
 - [Java auto-format with Eclipse](./guides/java_auto_format_eclipse.md)
 - [Kubernetes](./guides/kubernetes.md)
 - [Managing Application Credentials](./guides/application_credentials.md)

docs/guides/README.md

@@ -32,6 +32,8 @@ Security issues can arise when one code component incorrectly assumes another ha
 
 Keep secrets such as passwords and private keys logically isolated from the core code base. This will help prevent them being checked in to public code repositories. Hard coding credentials in source code is bad practice.
 
+See the [GitHub Advanced Security guide](github_advanced_security.md) for how Defra uses secret scanning and push protection to detect and prevent secret exposure.
+
 ### Do small and regular code commits
 
 Performing effective review becomes more difficult when large changes are made with each commit. Small and clearly labelled commits simplify the review and roll back process.

docs/guides/github_advanced_security.md

@@ -0,0 +1,103 @@
+# GitHub Advanced Security
+
+[GitHub Advanced Security (GHAS)](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) is GitHub's suite of built-in security features. It is enabled on every repository in the Defra GitHub organisation.
+
+GHAS includes:
+
+- **Secret scanning** - detects secrets such as API keys and tokens committed to code
+- **Push protection** - proactively blocks pushes that contain detected secrets
+- **Dependabot** - identifies vulnerable or outdated dependencies and can automatically raise pull requests to address them
+- **Code scanning** - performs static analysis to surface potential security vulnerabilities in code
+
+Teams should maximise use of these built-in features. See the [security standards](../standards/security_standards.md) for configuration expectations.
+
+## Secret scanning
+
+GitHub scans all commits for secrets such as passwords, API keys, and tokens. Alerts appear under the **Security and Quality** tab in your repository and are also visible in the [Defra security overview](https://github.com/orgs/DEFRA/security/overview).
+
+There are two types of alert:
+
+- **Default alerts** - match GitHub's known secret patterns, plus any custom patterns added for the Defra organisation. These are higher confidence.
+- **Generic alerts** - detected by GitHub's AI analysis and do not follow a known provider pattern. These have a higher rate of false positives.
+
+Alerts indicate _potential_ secret exposure that needs investigation, not confirmed exposure. Archived repositories are included in secret scanning results - even though the code is no longer maintained, the secret value may still be active.
+
+View all secret scanning alerts for the Defra org:
+
+- [Default secret alerts](https://github.com/orgs/DEFRA/security/alerts/secret-scanning)
+- [Generic secret alerts](https://github.com/orgs/DEFRA/security/alerts/secret-scanning?query=is%3Aopen+results%3Ageneric)
+
+### Push protection
+
+[Push protection](https://docs.github.com/en/code-security/secret-scanning/introduction/about-push-protection) is enabled across the Defra organisation. GitHub will block a push if it detects a potential secret in the code before it is published to the repository.
+
+Only an **admin** can bypass push protection. If you believe a detection is a false positive, you can submit a bypass request through the GitHub UI by providing a reason.
+
+**You must then post in the [`#github-support`](https://defra-digital.slack.com/archives/C015VCNLKFE) channel on the defra-digital Slack to have your request actioned.** Include:
+
+- a link to the bypass request
+- a brief explanation of why the protection should be bypassed
+
+See the [resolving GitHub security alerts](../processes/github_security_alerts.md) process for full details.
+
+### Custom secret patterns
+
+The Defra organisation has custom secret patterns in addition to GitHub's defaults. Teams can request new custom patterns by posting in [`#github-support`](https://defra-digital.slack.com/archives/C015VCNLKFE) on the defra-digital Slack.
+
+### If a secret has been exposed
+
+If a secret has already been committed and published, follow the [credential exposure process](../processes/credential_exposure.md). The key point is: once exposed, always treat the secret as compromised - rotate it immediately regardless of how quickly the commit was removed.
+
+## Vulnerability alerts
+
+[Dependabot](https://docs.github.com/en/code-security/dependabot) scans your repository's dependencies against the GitHub Advisory Database and raises alerts when a vulnerability is detected. It can also automatically raise pull requests to update affected packages.
+
+Vulnerability alerts appear in the **Security and Quality** tab of your repository and in the [Defra vulnerabilities overview](https://github.com/orgs/DEFRA/security/alerts/dependabot).
+
+Vulnerabilities in dependencies are common across all languages and frameworks. A new vulnerability alert does not mean the code has changed - it means someone has discovered a new way to exploit existing code. The risk is failing to respond to that information.
+
+Teams should:
+
+- regularly review Dependabot alerts in their repositories
+- action alerts promptly - either by patching the dependency or dismissing the alert with a reason
+
+Only an **admin** can dismiss a Dependabot alert. If you need to dismiss one, submit the dismissal through the GitHub UI and then post in [`#github-support`](https://defra-digital.slack.com/archives/C015VCNLKFE) to have it approved. 
+
+Include:
+- a link to the dismissal request
+- a brief explanation of why the alert can be dismissed
+
+See the [resolving GitHub security alerts](../processes/github_security_alerts.md) process for full details.
+
+## Code scanning
+
+[Code scanning](https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning) uses [CodeQL](https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql) to perform static analysis on your code and surface potential security vulnerabilities. Alerts appear in the **Security and Quality** tab of your repository.
+
+Like Dependabot alerts, code scanning alert dismissals require admin approval - post in [`#github-support`](https://defra-digital.slack.com/archives/C015VCNLKFE) with a link to the dismissal and a brief reason.
+
+## Security overview
+
+The [Defra security overview](https://github.com/orgs/DEFRA/security/overview) provides an org-wide breakdown of potential threats across all repositories. It includes:
+
+- [**Malware**](https://github.com/orgs/DEFRA/security/alerts/malware) - repositories potentially containing known malware
+- [**Vulnerabilities**](https://github.com/orgs/DEFRA/security/alerts/dependabot) - repositories with known dependency vulnerabilities that have not been archived
+- [**Default secrets**](https://github.com/orgs/DEFRA/security/alerts/secret-scanning) - potential secrets matching known provider patterns or custom org patterns
+- [**Generic secrets**](https://github.com/orgs/DEFRA/security/alerts/secret-scanning?query=is%3Aopen+results%3Ageneric) - potential secrets detected by AI analysis
+
+## Monitoring security alerts
+
+Teams are responsible for staying on top of security alerts in their repositories.
+
+### Repository Security tab
+
+The **Security and Quality** tab in every GitHub repository shows all open Dependabot, code scanning, and secret scanning alerts. Review it regularly - alerts appear as soon as they are detected, without needing to trigger a build.
+
+### GitHub notifications
+
+You can configure [GitHub notifications](https://docs.github.com/en/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications) to receive alerts for security vulnerabilities in repositories you watch. This helps teams respond to new alerts promptly.
+
+### Dismissing or bypassing alerts
+
+Only an **admin** can bypass push protection or dismiss a security alert. In all cases, post in [`#github-support`](https://defra-digital.slack.com/archives/C015VCNLKFE) on the defra-digital Slack with a link to the request and a brief reason.
+
+See the [resolving GitHub security alerts](../processes/github_security_alerts.md) process for full details.

docs/processes/credential_exposure.md

@@ -12,20 +12,22 @@ This process will take you through what to do if that happens. The key point is
 
 No matter the speed with which you rectify the situation, or how little you think the chance is for people to see it. Treat it as compromised.
 
+Deleting the repository or making it private are not solutions. The secret may have been cached by GitHub, or forked by someone else. You need to treat it as compromised and rotate it.
+
 ## Contact operations
 
 The first step is to make contact with the team responsible for your production environment.
 
-For example if your service is hosted in AWS, you should call someone from the AWS web-ops team ([David Blackburn](https://github.com/davidblackburn) or [Tom Tant](https://github.com/TTEA1990)).
-
-We cannot post contact numbers here. But they are available using our internal systems.
+For example if your service is hosted in AWS or Azure, you should raise an incident with the Cloud Centre of Excellence (CCoE).
 
 Follow this up with an email that contains a link to the commit, and explains what was exposed.
 
 ## Fix your git
 
 Next is fix your git tree. This involves removing the offending commit from your git history.
 
+> In some cases rewriting history would add disproportionate complexity to the project. Particularly if the commit was some time ago.  In these cases it may be better to leave the commit in place if you can rotate the secret.
+
 ### On a branch
 
 If the commit was on a branch the fix involves amending or removing the commit. You can use git commands such as `git commit --amend` or `git rebase -i` to amend the current branches history.
@@ -44,7 +46,7 @@ To quote GitHub's guide
 
 > [..] *it's important to note that those commits may still be accessible in any clones or forks of your repository, directly via their SHA-1 hashes in cached views on GitHub, and through any pull requests that reference them.*
 
-If someone manages to fork or update their fork before you push your fix there is little you can do. Try to reach out to them to explain the situtation, and ask them to update their fork.
+If someone manages to fork or update their fork before you push your fix there is little you can do. Try to reach out to them to explain the situation, and ask them to update their fork.
 
 ### GitHub
 

docs/standards/continuous_integration.md

@@ -83,6 +83,8 @@ This includes vulnerabilities in GitHub actions themselves.
 
 Teams must resolve any open security alerts in their repositories.
 
+See the [GitHub Advanced Security guide](../guides/github_advanced_security.md) for more detail on alert types, push protection, and how to request approval to dismiss alerts.
+
 ### Maintainability and test coverage
 
 Defra has a [SonarQube Cloud](https://www.sonarsource.com/products/sonarcloud/) organisation, which must be used to perform static quality analysis checks on your code.

docs/standards/security_standards.md

@@ -12,7 +12,7 @@ Use the [OWASP Secure coding practices - quick reference guide](https://www.owas
 
 ## GitHub Advanced Security
 
-Defra has GitHub Advanced Security enabled across its organisation. Teams should maximise use of these built-in features rather than relying on third-party tools.
+Defra has GitHub Advanced Security enabled across its organisation. Teams should maximise use of these built-in features rather than relying on third-party tools. See the [GitHub Advanced Security guide](../guides/github_advanced_security.md) for a full explanation of the features and how to use them.
 
 ### Dependency graph
 
@@ -40,7 +40,7 @@ This means you do not need to wait for a build to run to discover a vulnerabilit
 
 ### Snyk
 
-Snyk has been assessed alongside GitHub Advanced Security. As GitHub Advanced Security provides largely equivalent capability and is already available to all Defra teams, teams should look to maximise usage of GitHub Advanced Security rather than relying on Snyk.
+Snyk has been assessed alongside [GitHub Advanced Security](../guides/github_advanced_security.md). As GitHub Advanced Security provides largely equivalent capability and is already available to all Defra teams, teams should look to maximise usage of GitHub Advanced Security rather than relying on Snyk.
 
 ### Significant changes