diff --git a/docs/_data/changelog.yml b/docs/_data/changelog.yml index d83f712b..82213a4c 100644 --- a/docs/_data/changelog.yml +++ b/docs/_data/changelog.yml @@ -1,3 +1,31 @@ +- date: '2026-09-08' + updates: + pipeline_connector: + version: 0.8.0 + breaking_changes: + - text: |- + Added support for new [Pipeline Policies](/pipeline-policies). The old build and source code policies under `.signpath/policies/*` are only loaded if explicitly referenced as Pipeline Policies and are modified to match the new policy definition scheme. + issues: [SIGN-8632, SIGN-8843, SIGN-8847, SIGN-8846, SIGN-8819] + bug_fixes: + - text: |- + TeamCity: The entire `/refs/heads/*` branch identifier is again used for Git branches instead of the shortened name (e.g. `main`). + issues: [SIGN-8826] + application: + version: 1.220.0 + new_features: + - text: |- + [Pipeline Policies](/pipeline-policies) allow central policy controls for restricting source code and build settings of your CI/CD pipeline . + issues: [] + jenkins_plugin: + version: 5.0.0 + breaking_changes: + - text: |- + The Jenkins Plugin now requires a Pipeline Connector instance to run. Contact [our support team](https://signpath.io/support) for details. + issues: [SIGN-8637] + new_features: + - text: |- + SCM [Pipeline Policies](/pipeline-policies) are now supported for Jenkins builds. + issues: [SIGN-8637] - date: '2026-08-25' updates: self_hosted_installations: diff --git a/docs/_data/editions.yml b/docs/_data/editions.yml index 4d31f5f5..bf9234db 100644 --- a/docs/_data/editions.yml +++ b/docs/_data/editions.yml @@ -7,10 +7,10 @@ projects-hint: quota-hint users: 'up to 2' users-hint: quota-hint - signign_requests_release: 'up to 60' - signign_requests_release-hint: quota-hint - signign_requests_test: 'up to 300' - signign_requests_test-hint: quota-hint + signing_requests_release: 'up to 60' + signing_requests_release-hint: quota-hint + signing_requests_test: 'up to 300' + signing_requests_test-hint: quota-hint ci_pipelines: '1' file_based_signing: authenticode: true @@ -55,7 +55,7 @@ origin_verification: false origin_policies: false build_validation: false - extended_policies: false + pipeline_policies: false user_management: sso: false scim: false @@ -81,10 +81,10 @@ projects-hint: 'You may use several artifact configurations per project, e.g. for different components. Click "buy now" and add projects to adjust quota.' users: 'up to 15' users-hint: quota-hint - signign_requests_release: 'up to 500' - signign_requests_release-hint: quota-hint - signign_requests_test: 'up to 2500' - signign_requests_test-hint: quota-hint + signing_requests_release: 'up to 500' + signing_requests_release-hint: quota-hint + signing_requests_test: 'up to 2500' + signing_requests_test-hint: quota-hint ci_pipelines: '1 per project' file_based_signing: authenticode: true @@ -129,7 +129,7 @@ origin_verification: false origin_policies: false build_validation: false - extended_policies: false + pipeline_policies: false user_management: sso: false scim: false @@ -146,14 +146,14 @@ gpg_key_management: false link_type: 'pricing_page' -- name: Advanced Code Signing - title: Advanced Code Signing +- name: Semantic Code Signing + title: Semantic Code Signing quotas: certificates: 'unlimited' projects: 'unlimited' users: 'unlimited' - signign_requests_release: 'unlimited' - signign_requests_test: 'unlimited' + signing_requests_release: 'unlimited' + signing_requests_test: 'unlimited' ci_pipelines: 'unlimited' file_based_signing: authenticode: true @@ -194,10 +194,79 @@ disable_malware_scanning: true pipeline_integrity: trusted_build_systems: optional - origin_verification: optional + origin_verification: false + origin_policies: false + build_validation: false + pipeline_policies: false + user_management: + sso: true + scim: true + groups: true + admin_delegation: true + other: + malware_detection: true + hsm_key_storage: true + available_on_premises: true + cert_enrollment: true + support: 'priority' + support-hint: 'Priority support using email, phone and screen sharing' + code_signing_consulting: 'available' + no_display: + gpg_key_management: true + link_type: 'sales_email' + +- name: Pipeline Integrity + title: Pipeline Integrity + quotas: + certificates: 'unlimited' + projects: 'unlimited' + users: 'unlimited' + signing_requests_release: 'unlimited' + signing_requests_test: 'unlimited' + ci_pipelines: 'unlimited' + file_based_signing: + authenticode: false + powershell: false + windows_scripting_host: false + clickonce: false + device_drivers: false + office_add_ins: false + opc: false + nuget: false + android: false + java: false + apk: false + rpm: false + deb: false + office_macros: false + xml: false + jsf: false + docker: false + sbom: false + dsse: false + smime: false + cms: false + gpg: false + raw: false + hash_based_signing: none + artifact_configuration: + deep_signing: true + multiple_configurations_per_project: true + metadata_constraints: true + user_defined_parameters: true + policy_enforcement: + manual_approval: true + quorum_approval: true + signing_policies_per_project: 'unlimited' + policies_for_certs: true + resubmit: true + disable_malware_scanning: true + pipeline_integrity: + trusted_build_systems: true + origin_verification: true origin_policies: true build_validation: true - extended_policies: true + pipeline_policies: true user_management: sso: true scim: true @@ -221,8 +290,8 @@ certificates: 'unlimited' projects: 'n/a' users: 'unlimited' - signign_requests_release: 'unlimited' - signign_requests_test: 'unlimited' + signing_requests_release: 'unlimited' + signing_requests_test: 'unlimited' ci_pipelines: 'unlimited' file_based_signing: none hash_based_signing: @@ -251,7 +320,7 @@ origin_verification-hint: Not supported by crypto providers origin_policies: true build_validation: true - extended_policies: true + pipeline_policies: false user_management: sso: true scim: true @@ -277,8 +346,8 @@ projects: 'unlimited' projects-hint: 'OSS teams must apply for each project individually.' users: 'unlimited' - signign_requests_release: 'fair use' - signign_requests_test: 'fair use' + signing_requests_release: 'fair use' + signing_requests_test: 'fair use' ci_pipelines: '1 per project' file_based_signing: authenticode: true @@ -323,7 +392,7 @@ origin_policies: 'required' build_validation: 'required' disable_malware_scanning: false - extended_policies: 'predefined' + pipeline_policies: true user_management: sso: false scim: false diff --git a/docs/_data/featuregroups.yml b/docs/_data/featuregroups.yml index a82f0879..5c978c4a 100644 --- a/docs/_data/featuregroups.yml +++ b/docs/_data/featuregroups.yml @@ -17,11 +17,11 @@ title: 'Signing requests' hint: 'Signing requests (think software packages or releases) per year. Each signing request may contain multiple files.' href: '/product/editions-explained#signing-requests' - - name: signign_requests_release + - name: signing_requests_release title: 'release-signing' hint: 'Signing requests using your EV certificate' class: f sub - - name: signign_requests_test + - name: signing_requests_test title: 'test-signing' hint: 'Signing request using a test certificate that must be installed on target machines. Used for testing the signing configuration, signing internal builds, release candidates etc.' class: f sub @@ -177,8 +177,8 @@ title: 'Build validation' hint: 'Automatically checks build configurations for security weaknesses.' class: f sub - - name: extended_policies - title: 'SCM and CI policy control' + - name: pipeline_policies + title: 'Pipeline Policies' hint: 'Define specific SCM and CI/CD policy requirements, e.g. branch protection or build agents' class: f sub diff --git a/docs/_data/menus/documentation.yml b/docs/_data/menus/documentation.yml index db34c9ad..582ed0d4 100644 --- a/docs/_data/menus/documentation.yml +++ b/docs/_data/menus/documentation.yml @@ -65,6 +65,9 @@ - text: Origin Verification path: origin-verification +- text: Pipeline Policies + path: pipeline-policies + - text: SLSA Attestations path: slsa-attestations items: diff --git a/docs/_data/pipeline-policy-schemas/github.yml b/docs/_data/pipeline-policy-schemas/github.yml new file mode 100644 index 00000000..0e210fcc --- /dev/null +++ b/docs/_data/pipeline-policy-schemas/github.yml @@ -0,0 +1,132 @@ +rules: + - type: creation + description: "Only allow users with bypass permission to create matching refs." + - type: update + description: "Only allow users with bypass permission to update matching refs." + - type: deletion + description: "Only allow users with bypass permissions to delete matching refs." + - type: required_linear_history + description: "Prevent merge commits from being pushed to matching refs." + - type: pull_request + description: "Require all commits be made to a non-target branch and submitted via a pull request before they can be merged." + parameters: + dismiss_stale_reviews_on_push: + description: "New, reviewable commits pushed will dismiss previous pull request review approvals." + method: equals + type: boolean + required: false + require_code_owner_review: + description: "Require an approving review in pull requests that modify files that have a designated code owner." + method: equals + type: boolean + required: false + require_last_push_approval: + description: "Whether the most recent reviewable push must be approved by someone other than the person who pushed it." + method: equals + type: boolean + required: false + required_approving_review_count: + description: "The number of approving reviews that are required before a pull request can be merged." + method: min + type: integer + required: false + required_review_thread_resolution: + description: "All conversations on code must be resolved before a pull request can be merged." + method: equals + type: boolean + required: false + - type: non_fast_forward + description: "Prevent users with push access from force pushing to refs." + - type: code_scanning + description: "Choose which tools must provide code scanning results before the reference is updated. When configured, code scanning must be enabled and have results for both the commit and the reference being updated." + parameters: + code_scanning_tools: + description: "Tools that must provide code scanning results for this rule to pass." + method: all_of + type: object array + required: true + properties: + alerts_threshold: + description: > + The severity level at which code scanning results that raise alerts block a reference update. For more information on alert severity levels, see "[About code scanning alerts](https://docs.github.com/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-alert-severity-and-security-severity-levels)." + method: min + type: enum + required: true + policy_type: array + enum: + - none + - errors + - errors_and_warnings + - all + security_alerts_threshold: + description: > + The severity level at which code scanning results that raise security alerts block a reference update. For more information on security severity levels, see "[About code scanning alerts](https://docs.github.com/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-alert-severity-and-security-severity-levels)." + method: min + type: enum + required: true + policy_type: array + enum: + - none + - critical + - high_or_higher + - medium_or_higher + - all + tool: + description: "The name of a code scanning tool" + method: one_of + type: string + required: true + policy_type: array + sample: CodeQL +# new rules - no tests yet + - type: required_signatures + description: "Require commits to be signed with a GPG key that is verified by GitHub." + - type: file_path_restriction + description: "Prevent commits that include changes in specified file and folder paths from being pushed to the commit graph. This includes absolute paths that contain file names." + parameters: + restricted_file_paths: + description: "The file paths that are restricted from being pushed to the commit graph." + method: all_of + type: string array + required: true + sample: "\n - 'src/config/local.env'" + - type: file_extension_restriction + description: "Prevent commits that include files with specified file extensions from being pushed to the commit graph." + parameters: + restricted_file_extensions: + description: "The file extensions that are restricted from being pushed to the commit graph." + method: all_of + type: string array + required: true + sample: "\n - '.sql'" + - type: max_file_path_length + description: "Prevent commits that include file paths that exceed the specified character limit from being pushed to the commit graph." + parameters: + max_file_path_length: + description: "The maximum amount of characters allowed in file paths." + method: max + type: integer + required: true + sample: '1024 # characters' + - type: max_file_size + description: "Prevent commits with individual files that exceed the specified limit from being pushed to the commit graph." + parameters: + max_file_size: + description: "The maximum file size allowed in megabytes. This limit does not apply to Git Large File Storage (Git LFS)." + method: max + type: integer + required: true + sample: '10 # mb' + - type: copilot_code_review + description: "Request Copilot code review for new pull requests automatically if the author has access to Copilot code review and their premium requests quota has not reached the limit." + parameters: + review_draft_pull_requests: + description: "Copilot automatically reviews draft pull requests before they are marked as ready for review." + method: equals + type: boolean + required: false + review_on_push: + description: "Copilot automatically reviews each new push to the pull request." + method: equals + type: boolean + required: false \ No newline at end of file diff --git a/docs/_includes/render-github-policies.html b/docs/_includes/render-github-policies.html new file mode 100644 index 00000000..4c8fe25e --- /dev/null +++ b/docs/_includes/render-github-policies.html @@ -0,0 +1,109 @@ + +{% if include.schema == nil or include.schema.rules == nil %} +
Error: schema argument missing or invalid
+{% endif %} + + + + + + + + + + + {%- for rule in include.schema.rules -%} + + + + + + {%- endfor -%} + +
TypeParametersDescription
{%- if rule.parameters -%}{%- endif -%}{{ rule.type }}{%- if rule.parameters -%}{%- endif -%}{%- if rule.parameters -%}Yes{%- endif -%}{{ rule.description }}
+ +{%- for rule in include.schema.rules -%} +{%- if rule.parameters -%} +
{{ rule.type }}
+

{{ rule.description }}

+{%- assign has_properties = false -%} +{%- for param in rule.parameters -%} + {%- if param[1].properties -%} + {%- assign has_properties = true -%} + {%- endif -%} +{%- endfor -%} +The following parameters are supported: + + + + + + {%- if has_properties -%} + + {%- endif -%} + + + + {%- for param in rule.parameters -%} + + + + {%- if has_properties -%} + + {%- endif -%} + + {%- endfor -%} + +
ParameterDescriptionProperties
{{ param[0]}}
({{ param[1].type }}{%- if param[1].required -%}; required{%- endif -%})		{{ param[1].description}}{% if param[1].method == "min" %}
Note: The value defines a required minimum. Higher values are accepted.{% endif %}{% if param[1].method == "max" %}
Note: The value defines a required maximum. Lower values are accepted.{% endif %}		 + {%- if param[1].properties -%} + + + + + + + + + + {%- for prop in param[1].properties -%} + + + + + + {%- endfor -%} + +
PropertyValuesDescription
{{ prop[0] }}{%- if prop[1].required -%}
(required){%- endif -%}		 + {%- if prop[1].type == 'enum' -%} + one of + {%- if prop[1].method == "min" or prop[1].method == "max" -%}
    {%- else -%}
      {%- endif -%} + {%- for enum in prop[1].enum -%} +
    • {{ enum }}
      • + {%- endfor -%} + {%- if prop[1].method == "min" or prop[1].method == "max" -%}
{%- else -%}{%- endif -%} + {%- else -%} + {{ prop[1].type }} + {%- endif -%} + 		{{ prop[1].description }} +{% if prop[1].method == "min" %} _Note: The value defines a required minimum. Higher values are accepted._{% endif %}{% if prop[1].method == "max" %} _Note: The value defines a required maximum. Lower values are accepted._{% endif %} +
+ {%- else -%} + – + {%- endif -%} +
+Example: +
+```yaml + github-scm-policies: + ruleset_constraints: + - rules: + - type: {{ rule.type }}{% if rule.parameters %} + parameters: {% for param in rule.parameters %} + {{ param[0] }}: {% if param[1].sample %}{{ param[1].sample }}{% else %}{% case param[1].type %}{% when "boolean" %}true{% when "integer" %}1{% when "string array" %} + - value{% when "object array" %} + - {% for prop in param[1].properties %}{% if forloop.first %}{{ prop[0] }}: {% else %}{{ prop[0] | prepend: " " }}: {% endif %}{% if prop[1].sample %}{{ prop[1].sample }}{% else %}{% case prop[1].type %}{% when "enum" %}{{ prop[1].enum | last }}{% when "string" %}value{% endcase %}{% endif %} + {% endfor %}{% endcase %}{% endif %}{% endfor %}{% endif %} +``` +
+{%- endif -%} +{%- endfor -%} \ No newline at end of file diff --git a/docs/pipeline-policies/index.md b/docs/pipeline-policies/index.md new file mode 100644 index 00000000..d99fe9e8 --- /dev/null +++ b/docs/pipeline-policies/index.md @@ -0,0 +1,48 @@ +--- +header: Pipeline Policies +layout: resources +toc: false +description: Documentation for using Pipeline Policies in SignPath +--- + +{% include editions.md feature="pipeline_integrity.pipeline_policies" %} + +Pipeline policies allow restricting source code and build settings of your CI/CD pipeline. + +Steps to create a Pipeline Policy: +1. In SignPath, create a Pipeline Policy with either an _internal_ definition, i.e. YAML pasted in the web interface or an _external_ definition stored in a source code repository. +2. For each [signing policy](/projects#signing-policies), one or more pipeline policies can be added. At submit time, the build system and source code management system settings are evaluated and compliance with the policy definition is checked. If the level is set to _Log_, a respective information entry is shown on the signing request page. If the level is set to _Enforce_, the signinig request is denied. + +# Example + +```yaml +github-build-policies: + version: '1.0' + disallow_reruns: false + runners: + require_github_hosted: true + allowed_groups: + - Hardened Runners + +github-scm-policies: + version: '1.0' + ruleset_constraints: + - enforced_from: 2025-01-01 + allow_bypass_actors: true + rules: + - type: non_fast_forward + - type: pull_request + parameters: + required_approving_review_count: 2 + require_last_push_approval: true +``` + +# Reference + +Pipeline Policies for the following systems are supported. See the respective pages for details: + +* Source Code Management (SCM) systems: + * [GitHub](/trusted-build-systems/github#github-scm-policies) (`github-scm-policies`) +* CI/CD systems: + * [GitHub Actions](/trusted-build-systems/github#github-build-policies) (`github-build-policies`) + * [Azure DevOps](/trusted-build-systems/azure-devops#azure-devops-build-policies) (`azure-devops-build-policies`) diff --git a/docs/trusted-build-systems/azure-devops.md b/docs/trusted-build-systems/azure-devops.md index 3263c412..fa1de0bc 100644 --- a/docs/trusted-build-systems/azure-devops.md +++ b/docs/trusted-build-systems/azure-devops.md @@ -97,4 +97,56 @@ The action supports the following output parameters: - `SigningRequestWebUrl`: URL of the signing request in SignPath UI. Available to subsequent tasks as environment variable `_SIGNINGREQUESTWEBURL`. - `SignedArtifactDownloadUrl`: download URL of the signed artifact. Available to subsequent tasks as environment variable `_SIGNEDARTIFACTDOWNLOADURL`. -_Note: `` is the value of the `name` property of the `SubmitSigningRequest` task._ \ No newline at end of file +_Note: `` is the value of the `name` property of the `SubmitSigningRequest` task._ + +## Pipeline Policies for Azure DevOps + +{% include editions.md feature="pipeline_integrity.pipeline_policies" %} + +You can define [pipeline policies](/pipeline-policies) that restrict source code and build settings. + +The available policies specific to Azure DevOps are listed in this section. + +### Example + +```yaml +azure-devops-build-policies: + version: 1.0 + agents: + allow_self_hosted: false + build: + disallow_classic_pipelines: true +``` + +### `azure-devops-build-policies` + +Allows to restrict the Azure DevOps build pipelines with the following policies: + + + + + + + + + + + + + + + + + + +
PolicyDescription
+```yaml + agents: + allow_self_hosted: false +``` +Restricts builds to AzureDevOps-hosted build agents.
+```yaml + build: + disallow_classic_pipelines: true +``` +Disallows classic pipelines.
diff --git a/docs/trusted-build-systems/github.md b/docs/trusted-build-systems/github.md index 543db3a8..c1e36273 100644 --- a/docs/trusted-build-systems/github.md +++ b/docs/trusted-build-systems/github.md @@ -2,7 +2,7 @@ header: GitHub layout: resources toc: true -show_toc: 2 +show_toc: 3 description: GitHub --- @@ -11,7 +11,7 @@ description: GitHub * Use the predefined Trusted Build System _GitHub.com_ (see [configuration](/trusted-build-systems#configuration)) * add it to the Organization * link it to each SignPath Project for GitHub -* Required for [source code and build policies](#define-policies-for-source-code-and-builds): Install the [SignPath GitHub App](https://github.com/apps/signpath) and allow access to the code repositories. +* Required for [audit log evaluation](#audit-log-evaluation): Install the [SignPath GitHub App] and allow access to the code repositories. {:.panel.info} > **GitHub Enterprise Server** @@ -72,7 +72,7 @@ steps: > > * the GitHub repository is private > * the workflow permissions are set to the default "Read repository contents and packages permissions" -> * The SignPath GitHub App is _not_ installed +> * The [SignPath GitHub App] is _not_ installed > > You can use the following snippet: > ``` @@ -115,95 +115,141 @@ The action supports the following output parameters: - `signing-request-web-url`: URL of the signing request in SignPath - `signed-artifact-download-url`: download URL of the signed artifact -## Define policies for source code and builds +## Pipeline Policies for GitHub -{% include editions.md feature="pipeline_integrity.extended_policies" %} +{% include editions.md feature="pipeline_integrity.pipeline_policies" %} -You can define specific source code and build policies for your repository per signing policy: +You can define [pipeline policies](/pipeline-policies) that restrict source code and build settings. -* `runners`: define which runners may be used by GitHub Actions -* `build`: define conditions for GitHub Actions workflows and runs -* `branch_rulesets`: define minimum requirements for branch rulesets including conditions for integrity, reviews, and code scanning +The available policies specific to GitHub are listed in this section. -Steps to create a policy file: +There are separate policy sections for GitHub's CI sytem, [GitHub Actions](#github-build-policies) (`github-build-policies`) and [GitHub's source code management system](#github-scm-policies) (`github-scm-policies`). -* create the policy file in the `default` branch of the source code repository -* name it `.signpath/policies//.yml` -* restrict write permissions to the policy files using GitHub's [code owners] feature +### Example -### Policy sections +```yaml +github-build-policies: + version: '1.0' + disallow_reruns: false + runners: + require_github_hosted: true + allowed_groups: + - Hardened Runners + +github-scm-policies: + version: '1.0' + ruleset_constraints: + - enforced_from: 2025-01-01 + allow_bypass_actors: true + rules: + - type: non_fast_forward + - type: pull_request + parameters: + required_approving_review_count: 2 + require_last_push_approval: true +``` -#### `runners` section -Use the `runners` section to define which runners may be used in the workflow run. +### `github-build-policies` -{%- include render-table.html table=site.data.tables.trusted-build-systems.github-extended-policies-runners -%} +Allows to restrict the GitHub Actions build with the following policies: -#### `build` section +| Top-Level Policy | Description +|-------------------|------------------------- +| `disallow_reruns` | Set to `true` to prevent signing builds from re-runs. By enforcing this policy, old, temporarily failed builds cannot be re-run and signed under the false impression that they include recent changes, such as vulnerability fixes. These builds would still be identified by their branch name, e.g. `main`. +| `runners` | Runner-specific settings, see table below. -Use the `build` section to configure rules for the build run. +{:.panel.info} +> **Limit to 3 re-runs** +> +> Due to performance reasons, SignPath currently allows policy evaluation for up to 3 re-runs of a build. Further re-runs with active policies will fail. -{%- include render-table.html table=site.data.tables.trusted-build-systems.github-extended-policies-build -%} +#### `runners` section -#### `branch_rulesets` section {#branch_rulesets} +| Policy | Description +|--------------------------|------------------- +| `required_github_hosted` | Set to `true` to ensure that all jobs of the workflow are executed on Github-hosted runners. +| `alllowed_groups` | Provide a list of GitHub runner group names. Ensures that all jobs of the workflow are executed on runners from one of the listed groups. -Use the `branch_rulests` section to configure conditions for [GitHub branch rulesets]. +### `github-scm-policies` -* You can configure branch rulesets in GitHub on an organization or repository level. SignPath verifies that there is at least one branch ruleset for each specified condition. -* Rules define minimum requirements that may be exceeded by the actual branch ruleset. +Allows to define `ruleset_constraints` for [GitHub branch rulesets]. All specified constraints must be covered by one or multiple active branch rulesets defined in GitHub. Multiple `ruleset_constraints` with different parameters can be defined. -##### How `branch_rulesets` conditions are evaluated +{:.panel.info} +> **How ruleset constraints map to GitHub ruleset rules** +> +> GitHub allows you to define **_branch rulesets_**, both for repositories and at an organization level. Each branch ruleset defines a set of _rules_ and, optionally, a set of _bypass actors._ +> +> SignPath allows you to define **_ruleset contraints_**. Every _rule_ in a _ruleset constraint_ defined in SignPath's policies must be fulfilled by at least one _rule_ in a _branch ruleset_ on GitHub. You can define whether _bypass actors_ are allowed and whether the constraint has to be continually fulfilled (see below). +> +> **_Example:_** +> +> For example, the following GitHub branch rulesets would fulfill all of the defined ruleset constraints: +> +> 1. The `non_fast_forward` constraint is covered by Ruleset 1 +> 2. The `deletion` constraint is covered by Ruleset 1. It would allow bypass actors, but disallowing them is stricter and therefore valid. +> 3. The `creation` constraint is covered by Ruleset 2. +> +> +> +> +> +> +> +> +> +> +> +> +> +> +>
SignPath constraintsGitHub branch rulesets
+> ```yaml +> github-scm-policies: +> ruleset_constraints: +> - allow_bypass_actors: false +> rules: +> - type: non_fast_forward +> - allow_bypass_actors: true +> rules: +> - type: deletion +> - type: creation +> ``` +> +> Ruleset 1 (does not allow bypass actors) +> * non_fast_forward +> * deletion +> +> Ruleset 2 (allows bypass actors) +> * creation +>
-You can group your policy requirements into multiple conditions, each containing a combination of rules, bypassers, and enforcement date: +#### General parameters for `ruleset_constraints` -| Section | Values | Description +| Parameter | Values | Description |-------------------------|--------------------------------|---------------------------- -| `rules` | See below | Rules that must be implemented by one ore more active branch rulesets | `allow_bypass_actors` | boolean | If `true`, the branch ruleset is allowed to define bypassers -| `enforced_from` | None, timestamp, or `EARLIEST` | By default, the rules are only evaluated at the time of signing. When provided, defines that these rules must have been in place from the specified date (YAML ISO timestamp) or earliest availability of audit log entries (`EARLIEST`). +| `enforced_from` | `CURRENT_BUILD` (default), timestamp or `EARLIEST` | By default, the constraints are only evaluated at the time of signing (`CURRENT_BUILD`). When another value is set for `enforced_from`, the constraints must have been continously fulfilled from the specified date (YAML ISO timestamp) or earliest availability of audit log entries (`EARLIEST`). {:.panel.info} +> **GitHub export** +> +> The SignPath policies are an extension and therefore compatible with the export format in GitHub. You can export a branch ruleset in GitHub, convert it to YAML and then paste the entire `rules` section under `ruleset_constraints` in your SignPath policies. + +{:.panel.info#audit-log-evaluation} > **About `enforced_from` evaluation** > > Depending on your GitHub subscription, the continuous enforcement of policies is either based on: > -> * **Audit log events** for _GitHub Enterprise_ subscriptions. Audit log events are only available for the last 180 days, any prior policy violations will not be detected. +> * **Audit log events** for _GitHub Enterprise_ subscriptions. Audit log events are only available for the last 180 days, any prior policy violations will not be detected. _Audit Log evaluation requires the [SignPath GitHub App] to be installed._ > * The **last modified date** of the branch rulesets for all other subscriptions. At least one branch ruleset that has not been modified since the specified timestap must implement the rule. -##### Available `branch_rulesets` rules +#### Supported rules -{%- include render-table.html table=site.data.tables.trusted-build-systems.github-extended-policies-branch-ruleset-rules -%} +The following rules are supported: -### Example - -```yaml -# .signpath/policies/my-project-slug/release-signing.yml - -github-policies: - runners: - allowed_groups: - - 'MySecureRunners' # all jobs need to run on runners in the specified group - build: - disallow_reruns: true - branch_rulesets: - - condition: - rules: - - block_force_pushes: # force pushes are prevented - - require_pull_request: # code reviews are required - min_required_approvals: 1 - require_code_owner_review: true - allow_bypass_actors: false # no-one is allowed to bypass this rule - enforced_from: EARLIEST # rule enforcement history is checked - - condition: - rules: - - require_code_scanning: # code scanning must not reveal problems - tools: - - tool: CodeQL - min_alerts_threshold: errors - min_security_alerts_threshold: medium - allow_bypass_actors: true # some people may bypass these rules - enforced_from: '2025-01-01 00:00' # had to be reset at some point -``` +{%- include render-github-policies.html schema=site.data.pipeline-policy-schemas.github -%} [code owners]: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners [GitHub branch rulesets]: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets +[SignPath GitHub App]: https://github.com/apps/signpath \ No newline at end of file diff --git a/docs/trusted-build-systems/jenkins.md b/docs/trusted-build-systems/jenkins.md index ffe238f5..60f797c8 100644 --- a/docs/trusted-build-systems/jenkins.md +++ b/docs/trusted-build-systems/jenkins.md @@ -9,7 +9,7 @@ description: Jenkins Plugin ## Prerequisites * The Jenkins plugin has been installed on the respective Jenkins instance (Jenkins 2.359 or higher are supported). -* The plugin has been registered as a _custom_ Trusted Build System within SignPath and linked to the respective project (see the [configuration](/trusted-build-systems#configuration) section). +* A Pipeline Connector instance ([Contact our support team](https://signpath.io/support) for details) is configured to reach the Jenkins server. * The following plugins are installed on the Jenkins server: * [Credentials binding](https://plugins.jenkins.io/credentials-binding/) * [Git](https://plugins.jenkins.io/git/) @@ -17,10 +17,10 @@ description: Jenkins Plugin ## Performed checks -The plugin ensures that +SignPath ensures that * A build was actually performed by a specific Jenkins CI instance, not by some other entity in possession of the API token * [Origin metadata](/origin-verification) is provided by Jenkins CI, not the build script, and can therefore not be forged -* The artifact is stored as an immutable Jenkins artifact before it is submitted for signing +* The artifact originated from the Jenkins build ## Installation @@ -28,9 +28,8 @@ See the [official plugin page](https://plugins.jenkins.io/signpath/) on how the ### Configuration -* The _Trusted Build System Token_ needs to be stored in a _System_ Credential (Under _Manage Jenkins / Manage Credentials_) +* In the _Code Signing with SignPath_ section of the System settings, set the _Connector URL_ and _Endpoint Slug_ of the installed Pipeline Connector and optionally define a default organization ID. * The _Api Token_ of a SignPath user with submitter permissions needs to be available to the build pipelines of the respective projects. -* The default credential ID for the _Trusted Build System Token_, the default organization ID and the SignPath API endpoint can be configured in the plugin configuration (under _System_ in the _Code Signing with SignPath_ section). ## Usage