Organization Code Security Configuration

Definition of a Code Security Configuration on organization level, the following properties are supported:

A feature set to not_set is not changed on the repositories the configuration is attached to, while properties set to null are not managed by otterdog, e.g. because the feature is not available to every organization.

Only configurations of the organization are managed, the predefined configurations of GitHub (e.g. GitHub recommended) and configurations of an enterprise are neither created, updated nor deleted. The name identifies a configuration: renaming a configuration deletes it and creates a new one, which is not attached to the repositories of the previous configuration anymore.

A configuration is attached to a repository with the code_security_configuration property of the Repository, and to new repositories with the default_for_new_repos property. The configuration is attached before the other settings of the repository are applied, and otterdog waits until GitHub completed the attachment, as well as until an updated configuration is applied to its repositories. The patches of the repositories that an update is not applied to, as it failed or is still pending after 30 seconds, are skipped and reported as errors, as they might depend on the updated settings, as well as the patches of the repositories attached to a configuration whose update or deletion failed, or of all repositories if the attached ones can not be retrieved. Archived repositories support code security configurations, only secret scanning runs while they are archived.

The settings of a repository that the configuration attached to it sets are not managed on the repository, as the configuration takes precedence, and changing them on the repository might detach it from its configuration. This applies to the configuration the repository specifies, otherwise the one currently attached to it, even if it is not managed (e.g. GitHub recommended) or not deleted as --delete-resources is not used, or for a new repository, the default configuration for its visibility, unless default_code_security_configurations_disabled is enabled:

Features set to not_set leave the settings of the repository unchanged, they are still managed on the repository. GitHub supports private vulnerability reporting only on public repositories, a configuration does not enable it on private repositories. For a feature that the configuration does not specify, its current value on GitHub applies. When the current settings of repositories are not retrieved from GitHub, e.g. for the local apply of the dashboard, the settings that their configuration stops setting are applied again, as the configuration might have changed them on GitHub.

Bypass Reviewers¶

The entries of secret_scanning_delegated_bypass_reviewers reference teams and roles like the bypass actors of rulesets:

By default, a reviewer reviews the requests to bypass push protection. With the suffix :exempt, e.g. @OtterdogTest/release-bots:exempt, the reviewer is exempt from push protection instead.

Jsonnet Function¶

orgs.newOrgCodeSecurityConfiguration('<name>') {
  <key>: <value>
}

Default values¶

The default configuration of otterdog creates a code security configuration with the following values. Its features are disabled, except the dependency graph: attaching a configuration disables the features it does not enable on the repository, set a feature to not_set to leave it to the repositories.

# Function to create a new organization code security configuration with default settings.
# Settings set to null are not managed, e.g. as they are not available to every organization.
local newOrgCodeSecurityConfiguration(name) = {
  name: name,
  description: "",

  # GitHub Code Security and GitHub Secret Protection
  code_security: "disabled",
  secret_protection: "disabled",

  # dependency graph and Dependabot
  dependency_graph: "enabled",
  dependency_graph_autosubmit_action: "disabled",
  dependency_graph_autosubmit_action_labeled_runners: null,
  dependabot_alerts: "disabled",
  dependabot_security_updates: "disabled",
  dependabot_reachability: null,
  dependabot_delegated_alert_dismissal: null,

  # code scanning
  code_scanning_default_setup: "disabled",
  code_scanning_default_setup_runner_type: null,
  code_scanning_default_setup_runner_label: null,
  code_scanning_allow_advanced: null,
  code_scanning_delegated_alert_dismissal: null,

  # secret scanning
  secret_scanning: "disabled",
  secret_scanning_push_protection: "disabled",
  secret_scanning_delegated_bypass: "disabled",
  secret_scanning_delegated_bypass_reviewers: null,
  secret_scanning_validity_checks: "disabled",
  secret_scanning_non_provider_patterns: "disabled",
  secret_scanning_generic_secrets: null,
  secret_scanning_generic_secrets_push_protection: null,
  secret_scanning_delegated_alert_dismissal: null,
  secret_scanning_extended_metadata: null,

  private_vulnerability_reporting: "disabled",
  enforcement: "enforced",

  # the visibility of new repositories this configuration is applied to by default:
  # 'none', 'all', 'public' or 'private_and_internal'
  default_for_new_repos: "none",
};

The default configuration of an instance of otterdog, set by base_template, might define other values, see otterdog show-default or the Defaults page of a project in the dashboard.

Validation rules¶

• specifying a value that is not allowed for a property triggers an error
• specifying a description longer than 255 characters triggers an error
• setting code_scanning_default_setup_runner_type to labeled without a code_scanning_default_setup_runner_label triggers an error
• specifying a bypass reviewer that is neither a team nor a role, or with a mode other than always or exempt, triggers an error
• setting the same visibility of new repositories in default_for_new_repos of several configurations triggers an error
• setting default_for_new_repos while default_code_security_configurations_disabled of the organization settings is enabled triggers an error
• enabling a feature of secret scanning while secret_protection is disabled triggers an error
• enabling code_scanning_default_setup or code_scanning_delegated_alert_dismissal while code_security is disabled triggers an error
• setting code_security and secret_protection to a different status for an organization with free plan triggers an error
• enabling secret_scanning_delegated_bypass without any secret_scanning_delegated_bypass_reviewers triggers a warning
• enabling a feature of secret scanning while secret_scanning is disabled triggers a warning
• enabling secret_scanning_delegated_bypass while secret_scanning_push_protection is disabled triggers a warning
• enabling dependabot_security_updates while dependabot_alerts is disabled triggers a warning

Example usage¶

orgs.newOrg('my-project', 'my-org') {
  settings+: {
    default_code_security_configurations_disabled: false,
  },
  code_security_configurations+: [
    orgs.newOrgCodeSecurityConfiguration('baseline') {
      description: "Baseline configuration for all new repositories",
      code_security: "enabled",
      secret_protection: "enabled",
      dependabot_alerts: "enabled",
      dependabot_security_updates: "enabled",
      secret_scanning: "enabled",
      secret_scanning_push_protection: "enabled",
      secret_scanning_delegated_bypass: "enabled",
      secret_scanning_delegated_bypass_reviewers: [
        "#OrganizationAdmin",
      ],
      default_for_new_repos: "all",
    },
  ],
  _repositories+:: [
    orgs.newRepo('my-repo') {
      code_security_configuration: "baseline",
    },
  ],
}