From 587435e13c9d0d0c593334d08c45d896c93abbe2 Mon Sep 17 00:00:00 2001 From: "well-architected-sync-bot[bot]" <235114805+well-architected-sync-bot[bot]@users.noreply.github.com> Date: Fri, 1 May 2026 09:18:00 +0000 Subject: [PATCH 1/5] Sync from github/github-well-architected-internal (main) Source Repository: github/github-well-architected-internal Source Branch: main Source SHA: c10f089f0c1b8c2bba17327327ddba6414c39883 --- CONTRIBUTING.md | 2 +- .../recommendations/securing-developer-workspace.md | 2 +- .../managing-repositories-at-scale/rulesets-best-practices.md | 2 +- content/library/productivity/quick-links.md | 2 +- content/library/scenarios/nist-ssdf-implementation.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 974cbc1..a65386f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -411,7 +411,7 @@ See [Framework Overview] for details on each pillar. - Keep sentences **short and clear** - Avoid unnecessary jargon - Include practical examples -- Prefer GitHub Docs links to **Enterprise Cloud**: `https://docs.github.com/en/enterprise-cloud@latest` (unless the guidance is specific to GitHub Enterprise Server) +- Prefer GitHub Docs links to **Enterprise Cloud**: `https://docs.github.com/enterprise-cloud@latest` (unless the guidance is specific to GitHub Enterprise Server) - Use Hugo shortcodes to keep articles consistent (see `archetypes/default.md`): - Further assistance: `{{% seeking-further-assistance-details %}}` - Related links: `{{% related-links-github-docs %}}` diff --git a/content/library/application-security/recommendations/securing-developer-workspace.md b/content/library/application-security/recommendations/securing-developer-workspace.md index b24b4fc..260715f 100644 --- a/content/library/application-security/recommendations/securing-developer-workspace.md +++ b/content/library/application-security/recommendations/securing-developer-workspace.md @@ -142,7 +142,7 @@ In addition to the development container best practices above, Codespaces enviro Third-party dependencies can introduce vulnerabilities into the development environment and the software supply chain. In fact, they are a leading cause of security incidents. It is essential to manage these dependencies carefully to minimize risk. This means reviewing and securing dependencies coming from package managers (like npm, PyPI, Maven, and NuGet), registries (which provide OCI images, Helm charts, and dev container features), OS-level packages (like apt, yum, and apk), and other sources. -- **Keep dependencies up to date**. Regularly update third-party libraries and packages to incorporate security patches and improvements. Use dependency management tools, such as [Dependabot](https://docs.github.com/en/enterprise-cloud@latest/dependabot), to automatically check for updates and vulnerabilities. When a new version is released, review the changelog for security-related fixes before updating. Prefer manual updates over automatic updates to ensure that changes are reviewed. Avoid mutable references. +- **Keep dependencies up to date**. Regularly update third-party libraries and packages to incorporate security patches and improvements. Use dependency management tools, such as [Dependabot](https://docs.github.com/en/enterprise-cloud@latest/code-security/getting-started/dependabot-quickstart-guide), to automatically check for updates and vulnerabilities. When a new version is released, review the changelog for security-related fixes before updating. Prefer manual updates over automatic updates to ensure that changes are reviewed. Avoid mutable references. - **Eliminate insecure packages**. Remove or replace packages that are no longer maintained or have known security issues. Vulnerabilities on developer machines can provide access to corporate networks, source code, and other sensitive resources. Use tools like Dependabot to identify and remediate vulnerable and outdated dependencies. Remember that multiple low- and medium-severity vulnerabilities will create a larger attack surface, creating new high- and critical-severity vulnerabilities; avoid accumulating these over time. - **Review all dependencies**. Before adding a new dependency, review its source code, documentation, and community reputation. Look for signs of active maintenance. Avoid packages with excessive permissions or those that execute code during installation without explicit user consent. Continuously review existing dependencies for security risks and remove any that are unnecessary. - **Restrict automatic code execution during package installation**. Configure package managers to block or prompt for confirmation before executing scripts during dependency installation. This prevents malicious code from running without developer awareness. For example, configure `ignore-scripts=true` in an `.npmrc` file to prevent `npm` from running lifecycle scripts by default. Placing this configuration in the project ensures that this setting applies to everyone that works with the code. In addition, creating this file at the user level (`$HOME/.npmrc` or `%USERPROFILE%\.npmrc`) ensures that you do not automatically run scripts when you restore a project that lacks this configuration. An easy way to apply user-level personalization is to use a [dotfiles](https://dotfiles.github.io/) repository to configure your development machine, [local dev containers](https://code.visualstudio.com/docs/devcontainers/containers#_personalizing-with-dotfile-repositories), or [Codespaces](https://docs.github.com/en/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account#dotfiles). This ensures that your preferred settings are automatically and consistently applied to each development environment. diff --git a/content/library/governance/recommendations/managing-repositories-at-scale/rulesets-best-practices.md b/content/library/governance/recommendations/managing-repositories-at-scale/rulesets-best-practices.md index 064c130..2c9d307 100644 --- a/content/library/governance/recommendations/managing-repositories-at-scale/rulesets-best-practices.md +++ b/content/library/governance/recommendations/managing-repositories-at-scale/rulesets-best-practices.md @@ -109,7 +109,7 @@ Enterprises need consistent, enforceable guardrails for how code enters, evolves - Grant bypass only to roles/teams with clear break-glass standard operating procedures. - Monitor bypass exceptions via the audit log, [REST API](https://docs.github.com/enterprise-cloud@latest/rest/repos/bypass-requests), webhooks, or the native [rule insights](https://docs.github.com/enterprise-cloud@latest/organizations/managing-organization-settings/managing-rulesets-for-repositories-in-your-organization#viewing-insights-for-rulesets) dashboard; look for patterns indicating a need to adjust rules. 6. Change management & versioning - - [Rulesest history](https://docs.github.com/enterprise-cloud@latest/organizations/managing-organization-settings/managing-rulesets-for-repositories-in-your-organization#using-ruleset-history) is retained for 180 days; you can view all the changes to a ruleset and revert back to a specific iteration. + - [Rulesets history](https://docs.github.com/enterprise-cloud@latest/organizations/managing-organization-settings/managing-rulesets-for-repositories-in-your-organization#using-ruleset-history) is retained for 180 days; you can view all the changes to a ruleset and revert back to a specific iteration. 7. Measurement & feedback - Metrics: % repos covered per tier, # blocked events by rule, mean time to remediate violation patterns, bypass frequency. - Use rule insights to adjust high-friction rules. diff --git a/content/library/productivity/quick-links.md b/content/library/productivity/quick-links.md index 8a1ceee..16e512c 100644 --- a/content/library/productivity/quick-links.md +++ b/content/library/productivity/quick-links.md @@ -3,7 +3,7 @@ # SPDX-License-Identifier: MIT title: Quick Links weight: 1 -prev: library/productivity/introduction +prev: library/productivity next: library/productivity/design-principles --- diff --git a/content/library/scenarios/nist-ssdf-implementation.md b/content/library/scenarios/nist-ssdf-implementation.md index 83d85e3..6cf9aab 100644 --- a/content/library/scenarios/nist-ssdf-implementation.md +++ b/content/library/scenarios/nist-ssdf-implementation.md @@ -845,7 +845,7 @@ jobs: 1. **Security alerts**: Review and triage alerts in the Security tab 2. **Dependabot security updates**: Automatically generate PRs for dependency updates 3. **Repository custom properties**: Use [custom properties](https://docs.github.com/enterprise-cloud@latest/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization) to classify repositories by business criticality, enabling risk-based prioritization of alerts -4. **Security campaigns**: Use [security campaigns](https://docs.github.com/enterprise-cloud@latest/code-security/securing-your-organization/tracking-security-work-across-your-organization/about-security-campaigns) to prioritize and coordinate remediation of specific alert types across repositories +4. **Security campaigns**: Use [security campaigns](https://docs.github.com/enterprise-cloud@latest/code-security/securing-your-organization/fixing-security-alerts-at-scale) to prioritize and coordinate remediation of specific alert types across repositories 5. **Copilot Autofix**: Use [Copilot Autofix](https://docs.github.com/enterprise-cloud@latest/code-security/code-scanning/managing-code-scanning-alerts/about-autofix-for-codeql-code-scanning) to automatically generate fix suggestions for vulnerabilities identified by CodeQL {{< callout type="info" >}} From 04184c34c486c241efa39ded96025f2860d8aba6 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 1 May 2026 12:26:21 +0000 Subject: [PATCH 2/5] Fix Install Dart Sass step to download from GitHub releases instead of snap Agent-Logs-Url: https://github.com/github/github-well-architected/sessions/96d61585-f96c-44b3-a03d-db9e11f66369 Co-authored-by: KittyChiu <42864823+KittyChiu@users.noreply.github.com> --- .github/workflows/pr-check.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/pr-check.yml b/.github/workflows/pr-check.yml index e473014..320a779 100644 --- a/.github/workflows/pr-check.yml +++ b/.github/workflows/pr-check.yml @@ -78,7 +78,10 @@ jobs: sudo dpkg -i ${{ runner.temp }}/hugo.deb hugo version - name: Install Dart Sass - run: sudo snap install dart-sass + run: | + curl -LJO https://github.com/sass/dart-sass/releases/download/1.83.4/dart-sass-1.83.4-linux-x64.tar.gz + tar -C $RUNNER_TEMP -xzf dart-sass-1.83.4-linux-x64.tar.gz + echo "$RUNNER_TEMP/dart-sass" >> $GITHUB_PATH - uses: actions/setup-node@v6 with: From ac13f05b0dc5925a671398f63dcace3a1c00ab24 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 1 May 2026 12:29:47 +0000 Subject: [PATCH 3/5] Revert changes from commit 04184c3 Agent-Logs-Url: https://github.com/github/github-well-architected/sessions/e9ab14a9-bf6e-4782-b68e-4639917979af Co-authored-by: KittyChiu <42864823+KittyChiu@users.noreply.github.com> --- .github/workflows/pr-check.yml | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/.github/workflows/pr-check.yml b/.github/workflows/pr-check.yml index 320a779..e473014 100644 --- a/.github/workflows/pr-check.yml +++ b/.github/workflows/pr-check.yml @@ -78,10 +78,7 @@ jobs: sudo dpkg -i ${{ runner.temp }}/hugo.deb hugo version - name: Install Dart Sass - run: | - curl -LJO https://github.com/sass/dart-sass/releases/download/1.83.4/dart-sass-1.83.4-linux-x64.tar.gz - tar -C $RUNNER_TEMP -xzf dart-sass-1.83.4-linux-x64.tar.gz - echo "$RUNNER_TEMP/dart-sass" >> $GITHUB_PATH + run: sudo snap install dart-sass - uses: actions/setup-node@v6 with: From 0aee198f9019ae4e618f3d7f5e124b2ee54b989f Mon Sep 17 00:00:00 2001 From: "William H. Salazar" Date: Fri, 1 May 2026 08:42:01 -0700 Subject: [PATCH 4/5] Add device enforcement via Conditional Access Policies to securing-developer-workspace --- .../securing-developer-workspace.md | 113 +++++++++++------- 1 file changed, 71 insertions(+), 42 deletions(-) diff --git a/content/library/application-security/recommendations/securing-developer-workspace.md b/content/library/application-security/recommendations/securing-developer-workspace.md index 260715f..c9e9c3c 100644 --- a/content/library/application-security/recommendations/securing-developer-workspace.md +++ b/content/library/application-security/recommendations/securing-developer-workspace.md @@ -66,7 +66,7 @@ github: ## Scenario overview -Developer workspaces are where code is written, tested, and packaged before being committed to version control. These environments represent a critical security boundary in the software development lifecycle. A compromised developer workspace can lead to unauthorized access to source code, injection of malicious code, exposure of credentials, and supply chain attacks that affect downstream systems and users. Attacks in these environments can also target systems and services that developers interact with, such as cloud platforms and APIs. Remember that securing these environments is about minimizing the attack surface and reducing risk, not preventing trusted developers from being productive. +Developer workspaces are where code is written, tested, and packaged before being committed to version control. These environments represent a critical security boundary in the software development lifecycle, as they often have access to sensitive credentials, intellectual property, and production systems. Compromised developer workspaces can lead to supply chain attacks, data breaches, and unauthorized code injection. This article provides prescriptive guidance for securing developer workspaces. @@ -74,12 +74,12 @@ This article provides prescriptive guidance for securing developer workspaces. To secure your developer workspaces, consider the following strategies: -- **Implement strong identity authentication and workspace authorization**. Require multi-factor authentication (MFA) to access services like GitHub or Codespaces. Protect secrets used in development environments with secure storage solutions. -- **Implement workspace isolation**. Use local development containers (dev containers), remote dev containers (such as GitHub Codespaces), or temporary virtual machines (such as Microsoft Dev Box) to create consistent, isolated development environments that separate the development toolchain from the host system. -- **Implement least privileges**. Run containers as non-root users with restricted capabilities to limit the blast radius of potential security incidents. Images should be based on minimal, trusted base images and configured to prevent privilege escalation. Access to Git and other services should use the minimal possible privileges. -- **Require signed commits**. Implement commit signing to establish cryptographic proof of authorship and prevent unauthorized code injection. Require users to authenticate signing requests with a strong password or biometrics to ensure that commits can only be made by the developer. -- **Carefully review and manage third-party dependencies**. Use dependency management tools and services to monitor for vulnerabilities in third-party libraries and packages used in the development environment. Restrict packages from automatically updating without review. Block packages from executing code by default during installation/restore. -- **Secure AI-assisted development**. Review AI-generated code, dependencies, and configurations carefully to prevent vulnerabilities and supply chain attacks. Maintain human-in-the-loop controls and limit the tools and extensions that AI assistants can access. +- **Implement strong identity authentication and workspace authorization**. Require multi-factor authentication (MFA) to access services like GitHub or Codespaces. Protect secrets used in development and enforce device compliance through your identity provider to ensure only managed, healthy devices can access organizational resources. +- **Implement workspace isolation**. Use local development containers (dev containers), remote dev containers (such as GitHub Codespaces), or temporary virtual machines (such as Microsoft Dev Box) to isolate development environments from the host system and limit the blast radius of potential security incidents. +- **Implement least privileges**. Run containers as non-root users with restricted capabilities to limit the blast radius of potential security incidents. Images should be based on minimal, trusted base images and should be regularly updated to incorporate security patches. +- **Require signed commits**. Implement commit signing to establish cryptographic proof of authorship and prevent unauthorized code injection. Require users to authenticate signing requests with a strong authentication mechanism. +- **Carefully review and manage third-party dependencies**. Use dependency management tools and services to monitor for vulnerabilities in third-party libraries and packages used in the development environment. Regularly update dependencies to incorporate security patches and improvements. +- **Secure AI-assisted development**. Review AI-generated code, dependencies, and configurations carefully to prevent vulnerabilities and supply chain attacks. Maintain human-in-the-loop controls and stay informed about the evolving AI security landscape. ## Assumptions and preconditions @@ -94,37 +94,62 @@ This article assumes that: ### Identity authentication and workspace authorization -Developer workspaces must be protected by strong authentication mechanisms that verify the identity of users before granting access. For GitHub Codespaces and similar environments, this begins with proper authentication to GitHub itself. +Developer workspaces must be protected by strong authentication mechanisms that verify the identity of users before granting access. For GitHub Codespaces and similar environments, this begins with proper configuration of your identity provider (IdP) and enforcing the principle of least privilege across all access points. -- **Enable multi-factor authentication (MFA)**. Require MFA for all developers accessing workspaces. This can be enforced at the [GitHub organization settings](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization) or through an identity provider to ensure a consistent security posture. -- **Regular audits**. Periodically review access logs and permissions to identify any unauthorized access attempts or anomalies. Use [audit logs](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization) to monitor access patterns. +- **Enable multi-factor authentication (MFA)**. Require MFA for all developers accessing workspaces. This can be enforced at the [GitHub organization settings](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization) level or through your identity provider. +- **Regular audits**. Periodically review access logs and permissions to identify any unauthorized access attempts or anomalies. Use [audit logs](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization) to monitor access patterns and detect suspicious activity. + +#### Device compliance enforcement + +GitHub does not natively enforce managed versus unmanaged device access — this responsibility is delegated entirely to your Identity Provider (IdP) through **Conditional Access Policies (CAP)**. When a developer authenticates to GitHub, the IdP evaluates whether the device meets your compliance requirements before granting access. If the device becomes non-compliant mid-session, subsequent requests will be blocked — not just at login time. + +CAP enforcement requires [Enterprise Managed Users (EMU)](https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/understanding-iam-for-enterprises/about-enterprise-managed-users) and OIDC-based single sign-on. It is only supported with **Microsoft Entra ID** — not Okta or other IdPs — and **does not work with SAML**. This is one of the key reasons to prefer OIDC over SAML when device compliance enforcement is a requirement. + +With Entra ID CAP configured, you can enforce access based on: + +| Condition | What It Checks | +|---|---| +| **Device compliance** | Is the device Intune-compliant? | +| **Device join state** | Is the device Entra ID joined or hybrid joined? | +| **Platform** | Windows, macOS, iOS, Android, Linux | +| **Network location** | Is the user on a trusted/corporate network? | +| **Sign-in risk** | Is the sign-in flagged as risky by Entra ID? | +| **User risk** | Is the user account flagged as compromised? | + +Because GitHub has no native mechanism to inspect device state, a layered approach is essential to close remaining gaps: + +- **Enforce device compliance via your IdP**. Configure [Entra ID Conditional Access Policies](https://learn.microsoft.com/en-us/entra/identity/conditional-access/overview) to require Intune-compliant or Entra ID-joined devices. When combined with OIDC and EMU, CAP is validated on every GitHub request — web UI, API, Git over HTTPS, and fine-grained PATs — ensuring continuous enforcement rather than point-in-time checks at login. +- **Use an IP allow list as a complementary control**. Configure an [IP allow list](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization) for your GitHub organization or enterprise to restrict access to known corporate IP ranges. This ensures that developers must be on a managed network (such as a corporate VPN) to reach GitHub, providing an additional enforcement layer independent of the IdP. +- **Manage device configuration with MDM**. Use a Mobile Device Management (MDM) solution such as Microsoft Intune or Jamf to enforce device configuration policies, manage installed applications, and ensure security software is active. MDM policies can also restrict the use of personal GitHub accounts within organizational IDEs and tools. +- **Secure SSH access**. SSH-based Git access is harder to enforce through CAP alone. Complement IdP controls with [SSH certificate authorities](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities) to ensure that only devices with organizationally issued certificates can authenticate via SSH. Network-level controls (such as VPN requirements) provide an additional layer. +- **Recognize the limits of device enforcement**. GitHub has no visibility into local code once it has been cloned. Device compliance controls protect access to GitHub itself but cannot govern what happens on the developer's machine after checkout. Complement technical controls with acceptable use policies and endpoint security tooling. ### Implement workspace isolation -Securing local development containers, remote containers, and Codespaces ensures that development environments are isolated from the host system, following the principle of least privilege, and limit the attack surface. While specific configurations may vary based on project requirements, the following best practices should be considered when creating dev container configurations. +Securing local development containers, remote containers, and Codespaces ensures that development environments are isolated from the host system, following the principle of least privilege, and limiting the blast radius of potential security incidents. #### Development container best practices -- **Use minimal base images**. Start with minimal, well-maintained base images from trusted sources. Review base images for known vulnerabilities and unnecessary packages. Prefer images that are regularly maintained, provide provenance attestation, and are signed. Containers should be scanned for vulnerabilities as part of the build process. -- **Run as non-root user**. Configure the development container to run as a non-root user to limit the impact of potential security vulnerabilities. This prevents privilege escalation attacks and limits access to host resources. Specify the `containerUser` explicitly to ensure the user account for the container. -- **Limit Linux capabilities**. Use `runArgs` in the dev container configuration to drop unnecessary Linux capabilities (`--cap-drop=ALL`). Only add back capabilities that are explicitly required for development tasks or feature installation (such as `"capAdd": ["CHOWN"]` or `--cap-add=CHOWN` ). Avoid the use of `privileged` mode. -- **Prevent in-container privilege escalation**. Use the `--security-opt=no-new-privileges` option to prevent processes within the container from gaining additional privileges. Prefer images that are configured to prevent the user from escalating privileges using `sudo` or similar tools. +- **Use minimal base images**. Start with minimal, well-maintained base images from trusted sources. Review base images for known vulnerabilities and unnecessary packages. Prefer images that are regularly updated and have a small attack surface. +- **Run as non-root user**. Configure the development container to run as a non-root user to limit the impact of potential security vulnerabilities. This prevents privilege escalation attacks and limits the damage that can be done if the container is compromised. +- **Limit Linux capabilities**. Use `runArgs` in the dev container configuration to drop unnecessary Linux capabilities (`--cap-drop=ALL`). Only add back capabilities that are explicitly required for development tasks. +- **Prevent in-container privilege escalation**. Use the `--security-opt=no-new-privileges` option to prevent processes within the container from gaining additional privileges. Prefer images that are built with security in mind and do not require elevated privileges. - **Avoid exposing the Docker daemon socket**. Do not mount the Docker socket inside development containers, as this can allow privilege escalation to the host system. -- **Limit bind mounted directories**. For local development containers, prefer [isolated container volumes](https://code.visualstudio.com/docs/devcontainers/containers#_quick-start-open-a-git-repository-or-github-pr-in-an-isolated-container-volume) to store source code instead of bind mounts. This reduces the risk of exposing sensitive host files to the container, prevents the container from modifying host files, and improve performance. Prefer to avoid bind mounts which can expose host files to the container; when this is not possible, mounting the required resources as read-only. +- **Limit bind mounted directories**. For local development containers, prefer [isolated container volumes](https://code.visualstudio.com/docs/devcontainers/containers#_quick-start-open-a-git-repository-or-github-pr-in-an-isolated-container-volume) over bind mounts to reduce the risk of sensitive host files being accessed from within the container. - **Restrict network access**. Limit outbound and inbound network access from the development container to only necessary services and endpoints. This limits lateral movement in case of a compromise. -- **Review dev container features**. [Development container features](https://containers.dev/features) can simplify setup, but may introduce unnecessary dependencies or packages. Features run with elevated privileges during installation, so only include features that are necessary for the development environment. -- **Verify third-party tools and extensions**. Only install trusted extensions and tools within the development container. Review their source code, permissions, and community reputation to ensure they do not introduce vulnerabilities. Verify the publishers. Prefer trusted toolchains from official sources. +- **Review dev container features**. [Development container features](https://containers.dev/features) can simplify setup, but may introduce unnecessary dependencies or packages. Features run with elevated privileges during installation, so review them carefully before use. +- **Verify third-party tools and extensions**. Only install trusted extensions and tools within the development container. Review their source code, permissions, and community reputation to ensure they do not introduce security risks. - **Audit container logs**. Regularly review logs from the development container for suspicious activity or errors that may indicate security issues. If possible, integrate logging with centralized monitoring solutions. -- **Manage secrets securely**. Avoid hardcoding sensitive information such as API keys, passwords, or tokens in the dev container configuration or source code. Prefer OIDC and short-lived tokens to avoid storing long-lived credentials in the developer workspace. When storing secrets locally, use secure secret management solutions that require periodic re-authentication for access. Encrypt secrets when they are not actively in use. Minimize secrets exposed by environment variables or stored in unencrypted files. +- **Manage secrets securely**. Avoid hardcoding sensitive information such as API keys, passwords, or tokens in the dev container configuration or source code. Prefer OIDC and short-lived tokens to avoid long-lived credentials. #### Codespaces best practices In addition to the development container best practices above, Codespaces environments should also follow these additional security recommendations. -- **Leverage Codespaces secrets for sensitive credentials**. Use [Codespaces secrets](https://docs.github.com/en/enterprise-cloud@latest/codespaces/managing-your-codespaces/managing-secrets-for-your-codespaces) to securely store credentials needed during development. These secrets are encrypted and only available to the workspace at runtime, preventing exposure in configuration files or code. To prevent malicious access to secrets stored in the environment, consider adding an additional layer of encryption or using a secrets management tool that requires explicit access. Be aware that organization- and repository-level Codespaces secrets are accessible to anyone with permission to create a Codespace for that repository or within that organization. -- **Restrict repository permissions**. Restrict [Codespaces token permissions](https://docs.github.com/en/codespaces/managing-your-codespaces/managing-repository-access-for-your-codespaces) to the minimum necessary for development tasks. Prefer limiting access to `contents: write` for editable repositories, and `contents: read` for repositories that do not require write access. Avoid using wildcards (`*`) to grant access to all repositories. -- **Audit workspace access**. Use [audit logs](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization) to monitor when Codespaces are created, accessed, or deleted. Look for anomalous patterns that might indicate compromised credentials. -- **Define Codespaces policies**. Use [Codespaces policies](https://docs.github.com/en/codespaces/managing-codespaces-for-your-organization) to enforce appropriate security restrictions and to prevent unexpected billing charges. This includes: +- **Leverage Codespaces secrets for sensitive credentials**. Use [Codespaces secrets](https://docs.github.com/en/enterprise-cloud@latest/codespaces/managing-your-codespaces/managing-secrets-for-your-codespaces) to securely store and inject sensitive information into development environments without exposing them in source code or configuration files. +- **Restrict repository permissions**. Restrict [Codespaces token permissions](https://docs.github.com/en/codespaces/managing-your-codespaces/managing-repository-access-for-your-codespaces) to the minimum required for development tasks. Avoid granting broad access to organizational resources. +- **Audit workspace access**. Use [audit logs](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization) to monitor Codespaces activity and detect unauthorized access or anomalies. +- **Define Codespaces policies**. Use [Codespaces policies](https://docs.github.com/en/codespaces/managing-codespaces-for-your-organization) to enforce appropriate security restrictions and to prevent developers from creating overly permissive environments: - Restrict [allowed base images](https://docs.github.com/en/enterprise-cloud@latest/codespaces/managing-codespaces-for-your-organization/restricting-the-base-image-for-codespaces) - Restrict the [idle timeout period](https://docs.github.com/en/enterprise-cloud@latest/codespaces/setting-your-user-preferences/setting-your-timeout-period-for-github-codespaces) - Restrict the [available machine types](https://docs.github.com/en/enterprise-cloud@latest/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types) @@ -132,36 +157,36 @@ In addition to the development container best practices above, Codespaces enviro ### Signed commits -[Commit signing](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification) provides cryptographic proof that commits were created by a verified author and have not been tampered with. This is essential for maintaining code integrity and establishing trust in the software supply chain. GitHub supports GPG, SSH, and S/MIME X.509 certificates for commit signing. +[Commit signing](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification) provides cryptographic proof that commits were created by a verified author. This helps detect unauthorized code injection and establishes accountability for code changes. - **Use signed commits**. Require all developers to sign their commits to ensure authenticity. This makes it easy to validate the origin of code changes and detect unauthorized modifications. -- **Authenticate signing requests**. Ensure that signing keys are protected and that users must authenticate to use them. This prevents malicious actors or scripts from creating unauthorized commits by preventing automated signing without user consent. Agents should be configured to use short timeouts, log all access, and require biometric approval. Consider SSH keys stored in hardware tokens or devices that require physical touch when not using development containers or cloud services. -- **Enforce commit signing with rulesets**. Use [organization rulesets](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization) to require signed commits on protected branches. This prevents unsigned commits from being merged into critical branches. +- **Authenticate signing requests**. Ensure that signing keys are protected and that users must authenticate to use them. This prevents malicious actors or scripts from creating unauthorized commits by stealing unprotected signing keys. +- **Enforce commit signing with rulesets**. Use [organization rulesets](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization) to require signed commits across all repositories, ensuring consistent enforcement of commit signing policies. ## Third-party dependencies -Third-party dependencies can introduce vulnerabilities into the development environment and the software supply chain. In fact, they are a leading cause of security incidents. It is essential to manage these dependencies carefully to minimize risk. This means reviewing and securing dependencies coming from package managers (like npm, PyPI, Maven, and NuGet), registries (which provide OCI images, Helm charts, and dev container features), OS-level packages (like apt, yum, and apk), and other sources. +Third-party dependencies can introduce vulnerabilities into the development environment and the software supply chain. In fact, they are a leading cause of security incidents. It is essential to manage dependencies carefully and keep them up to date. -- **Keep dependencies up to date**. Regularly update third-party libraries and packages to incorporate security patches and improvements. Use dependency management tools, such as [Dependabot](https://docs.github.com/en/enterprise-cloud@latest/code-security/getting-started/dependabot-quickstart-guide), to automatically check for updates and vulnerabilities. When a new version is released, review the changelog for security-related fixes before updating. Prefer manual updates over automatic updates to ensure that changes are reviewed. Avoid mutable references. -- **Eliminate insecure packages**. Remove or replace packages that are no longer maintained or have known security issues. Vulnerabilities on developer machines can provide access to corporate networks, source code, and other sensitive resources. Use tools like Dependabot to identify and remediate vulnerable and outdated dependencies. Remember that multiple low- and medium-severity vulnerabilities will create a larger attack surface, creating new high- and critical-severity vulnerabilities; avoid accumulating these over time. -- **Review all dependencies**. Before adding a new dependency, review its source code, documentation, and community reputation. Look for signs of active maintenance. Avoid packages with excessive permissions or those that execute code during installation without explicit user consent. Continuously review existing dependencies for security risks and remove any that are unnecessary. -- **Restrict automatic code execution during package installation**. Configure package managers to block or prompt for confirmation before executing scripts during dependency installation. This prevents malicious code from running without developer awareness. For example, configure `ignore-scripts=true` in an `.npmrc` file to prevent `npm` from running lifecycle scripts by default. Placing this configuration in the project ensures that this setting applies to everyone that works with the code. In addition, creating this file at the user level (`$HOME/.npmrc` or `%USERPROFILE%\.npmrc`) ensures that you do not automatically run scripts when you restore a project that lacks this configuration. An easy way to apply user-level personalization is to use a [dotfiles](https://dotfiles.github.io/) repository to configure your development machine, [local dev containers](https://code.visualstudio.com/docs/devcontainers/containers#_personalizing-with-dotfile-repositories), or [Codespaces](https://docs.github.com/en/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account#dotfiles). This ensures that your preferred settings are automatically and consistently applied to each development environment. +- **Keep dependencies up to date**. Regularly update third-party libraries and packages to incorporate security patches and improvements. Use dependency management tools, such as [Dependabot](https://docs.github.com/en/enterprise-cloud@latest/code-security/dependabot/working-with-dependabot), to automate dependency updates and security alerts. +- **Eliminate insecure packages**. Remove or replace packages that are no longer maintained or have known security issues. Vulnerabilities on developer machines can provide access to corporate networks and sensitive data. +- **Review all dependencies**. Before adding a new dependency, review its source code, documentation, and community reputation. Look for signs of active maintenance. Avoid packages with excessive permissions or unusual installation scripts. +- **Restrict automatic code execution during package installation**. Configure package managers to block or prompt for confirmation before executing scripts during dependency installation. This prevents malicious packages from executing code on the developer's machine during installation. ### Secure AI-assisted development -AI coding assistants can accelerate development, but they also introduce unique security considerations. The code, dependencies, and configurations they generate require careful review to prevent vulnerabilities and supply chain attacks. Additionally, the tools and extensions that power AI assistants may themselves introduce security risks. +AI coding assistants can accelerate development, but they also introduce unique security considerations. The code, dependencies, and configurations they generate require careful review to prevent vulnerabilities and supply chain attacks. -- **Review AI-generated code carefully**. Code generated by AI tools may contain vulnerabilities, insecure patterns, or rely on vulnerable dependencies. Pay special attention to changes in workspace or pipeline configurations, which can introduce broader risks. Be aware that comments in code can be used to hide malicious instructions. -- **Review AI-acquired dependencies**. Verify that dependencies suggested or added by AI tools are trusted, up-to-date, and free of known vulnerabilities. Threat actors may publish packages that match commonly hallucinated package names, tricking developers into installing malicious code. -- **Review instruction files for prompt injection**. Files such as `copilot-instructions.md` or `AGENTS.md` are automatically injected into AI prompts. Review these files carefully to detect malicious instructions that could manipulate AI behavior. Configuration files, such as `settings.json` can be used to alter security settings or remove human-in-the-loop controls. -- **Maintain human-in-the-loop controls**. Avoid automating terminal command or code execution approval without review. Require explicit approval before AI tools can delete files, push code, or access remote repositories. Constraining automated behavior implements the principle of least privilege. -- **Evaluate Model Context Protocol (MCP) servers and tools**. These servers and tools can provide malicious commands or instructions that compromise security. They may also leak sensitive data through their API calls. Use only trusted tools and limit the number of active tools to reduce attack surface and preserve context. -- **Assess third-party AI models and services**. Third-party models may have been trained on insecure or malicious data, or could be configured to generate insecure code patterns. Review the security posture of any third-party AI tools or services used in the development environment, as they may leak sensitive data. +- **Review AI-generated code carefully**. Code generated by AI tools may contain vulnerabilities, insecure patterns, or rely on vulnerable dependencies. Pay special attention to changes in workspace or container configurations, dependency files, and security-sensitive code paths. +- **Review AI-acquired dependencies**. Verify that dependencies suggested or added by AI tools are trusted, up-to-date, and free of known vulnerabilities. Threat actors may publish packages that match common AI-suggested names to intercept installations (dependency confusion attacks). +- **Review instruction files for prompt injection**. Files such as `copilot-instructions.md` or `AGENTS.md` are automatically injected into AI prompts. Review these files carefully to detect malicious instructions that could alter AI behavior or exfiltrate sensitive information. +- **Maintain human-in-the-loop controls**. Avoid automating terminal command or code execution approval without review. Require explicit approval before AI tools can delete files, push code, or access external services. +- **Evaluate Model Context Protocol (MCP) servers and tools**. These servers and tools can provide malicious commands or instructions that compromise security. They may also leak sensitive data through their interfaces. Only use MCP servers from trusted sources and review their behavior carefully. +- **Assess third-party AI models and services**. Third-party models may have been trained on insecure or malicious data, or could be configured to generate insecure code patterns. Review the security posture of AI services before integrating them into your development workflow. - **Keep the IDE, tools, and extensions up to date**. Security patches and improvements are frequently released. Updates may include security enhancements for discovered vulnerabilities and exploits. -- **Avoid untrusted external content**. Images can contain hidden instructions in metadata or steganographic layers that manipulate LLM behavior. HTML or Markdown content may contain malicious scripts, instructions, or links. Fetching external content may also leak sensitive data. -- **Isolate untrusted repositories and projects**. Untrusted code may contain malicious dependencies, prompts, or configurations that can compromise the development environment. If you must open untrusted code, use an isolated environment and enable [Workspace Trust](https://code.visualstudio.com/docs/editing/workspaces/workspace-trust) features in VS Code to restrict permissions and capabilities. -- **Protect secrets from prompt exposure**. Avoid storing API keys, tokens, or other sensitive information in the workspace. This data may become part of the prompt context, exposing it to tools, external services, and the LLM. Use secure secret management solutions to store and access sensitive data. -- **Stay informed about AI security threats**. The security landscape for AI tools and LLMs is rapidly evolving. Follow security blogs, attend webinars, and participate in relevant communities to stay current on new vulnerabilities and mitigation strategies. +- **Avoid untrusted external content**. Images can contain hidden instructions in metadata or steganographic layers that manipulate LLM behavior. HTML or Markdown content may contain malicious scripts or prompt injection payloads. Be cautious when opening untrusted files in AI-assisted environments. +- **Isolate untrusted repositories and projects**. Untrusted code may contain malicious dependencies, prompts, or configurations that can compromise the development environment. If you must open untrusted code, do so in an isolated environment such as a disposable Codespace or VM. +- **Protect secrets from prompt exposure**. Avoid storing API keys, tokens, or other sensitive information in the workspace. This data may become part of the prompt context, exposing it to tools, extensions, or external AI services. +- **Stay informed about AI security threats**. The security landscape for AI tools and LLMs is rapidly evolving. Follow security blogs, attend webinars, and participate in relevant communities to stay current on emerging threats and mitigations. ## Seeking further assistance @@ -179,9 +204,13 @@ Specifically, you may find the following links helpful: - [Introduction to dev containers](https://docs.github.com/en/enterprise-cloud@latest/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers) - [Managing secrets for your codespaces](https://docs.github.com/en/enterprise-cloud@latest/codespaces/managing-your-codespaces/managing-secrets-for-your-codespaces) - [About rulesets](https://docs.github.com/en/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) +- [About Enterprise Managed Users](https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/understanding-iam-for-enterprises/about-enterprise-managed-users) +- [About SSH certificate authorities](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities) +- [Managing allowed IP addresses for your organization](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization) - [Safeguarding VS Code against prompt injections](https://github.blog/security/vulnerability-research/safeguarding-vs-code-against-prompt-injections/) ### External resources - [How I avoided Shai-Hulud's second coming (Part 1)](https://www.kenmuse.com/blog/how-i-avoided-shai-hulud-second-coming-part-1/) - [How I avoided Shai-Hulud's second coming (Part 2)](https://www.kenmuse.com/blog/how-i-avoided-shai-hulud-second-coming-part-2/) +- [Microsoft Entra Conditional Access overview](https://learn.microsoft.com/en-us/entra/identity/conditional-access/overview) From 6f17de4cd5b20aca880cac936e6c2229f1004092 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 1 May 2026 15:50:55 +0000 Subject: [PATCH 5/5] Fix Dart Sass install: replace snap with npm install -g sass Agent-Logs-Url: https://github.com/github/github-well-architected/sessions/ec1bb72f-a21a-467b-9d30-e04995972903 Co-authored-by: whsalazar <15836554+whsalazar@users.noreply.github.com> --- .github/workflows/pr-check.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/pr-check.yml b/.github/workflows/pr-check.yml index e473014..d98ded8 100644 --- a/.github/workflows/pr-check.yml +++ b/.github/workflows/pr-check.yml @@ -77,13 +77,14 @@ jobs: wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb sudo dpkg -i ${{ runner.temp }}/hugo.deb hugo version - - name: Install Dart Sass - run: sudo snap install dart-sass - uses: actions/setup-node@v6 with: node-version: lts/* + - name: Install Dart Sass + run: npm install -g sass + - name: Install test dependencies run: | # Clean install of the node modules