From 65701e622a488a713316293b4f142091fab007f9 Mon Sep 17 00:00:00 2001 From: Dan Barr Date: Thu, 9 Jan 2025 20:38:29 -0500 Subject: [PATCH 1/4] Format all docs files with Prettier --- docs/docs/about/_category_.yml | 2 +- docs/docs/about/changelog.md | 72 +++-- docs/docs/about/contributing.md | 28 +- docs/docs/about/roadmap.md | 79 ++++-- docs/docs/developer_guide/_category_.yml | 2 +- docs/docs/developer_guide/feature_flags.md | 89 ++++-- docs/docs/developer_guide/get-hacking.md | 34 ++- docs/docs/getting_started/enroll_provider.md | 33 ++- docs/docs/getting_started/first_profile.md | 60 ++-- docs/docs/getting_started/install_cli.md | 25 +- docs/docs/getting_started/login.md | 37 ++- docs/docs/getting_started/quickstart.md | 94 +++++-- docs/docs/getting_started/register_repos.md | 27 +- docs/docs/getting_started/remediations.md | 52 +++- docs/docs/getting_started/viewing_status.md | 67 +++-- docs/docs/how-to/artifact_signatures.md | 58 ++-- docs/docs/how-to/create_profile.md | 198 ++++++++----- docs/docs/how-to/create_project.md | 10 +- docs/docs/how-to/custom-rules.md | 163 ++++++++--- docs/docs/how-to/manage_profiles.md | 98 ++++--- docs/docs/how-to/mindev.md | 85 +++--- docs/docs/how-to/pr_reviews.md | 57 ++-- docs/docs/how-to/profile_selectors.md | 108 ++++--- docs/docs/how-to/remediate-pullrequest.md | 66 +++-- docs/docs/how-to/setup-alerts.md | 67 +++-- docs/docs/how-to/setup-autoremediation.md | 47 ++-- docs/docs/how-to/writing-rules-in-rego.md | 164 +++++++---- docs/docs/index.mdx | 38 ++- .../integrations/community_integrations.md | 83 ++++-- docs/docs/integrations/overview.md | 29 +- .../provider_integrations/github.md | 33 ++- docs/docs/integrations/stacklok-insight.md | 42 ++- docs/docs/ref/cli_configuration.md | 40 +-- docs/docs/ref/rules/artifact_signature.md | 36 ++- docs/docs/ref/rules/branch_protection.md | 208 +++++++++++--- docs/docs/ref/rules/codeql_enabled.md | 24 +- docs/docs/ref/rules/dependabot_configured.md | 24 +- docs/docs/ref/rules/github_actions.md | 58 ++-- docs/docs/ref/rules/license.md | 18 +- docs/docs/ref/rules/pr_trusty_check.md | 49 +++- docs/docs/ref/rules/pr_vulnerability_check.md | 109 +++++--- docs/docs/ref/rules/secret_scanning.md | 13 +- docs/docs/run_minder_server/config_oauth.md | 19 +- .../docs/run_minder_server/config_provider.md | 123 +++++--- docs/docs/run_minder_server/config_webhook.md | 59 ++-- .../run_minder_server/installing_minder.md | 133 +++++---- .../run_minder_server/intro_to_install.md | 16 +- docs/docs/run_minder_server/run_the_server.md | 126 ++++++--- docs/docs/understand/alerts.md | 81 +++--- docs/docs/understand/key_concepts.md | 264 +++++++++++------- docs/docs/understand/profiles.md | 72 +++-- docs/docs/understand/providers.md | 25 +- docs/docs/understand/remediations.md | 60 ++-- .../understand/repository_registration.md | 60 ++-- docs/docs/understand/rule_evaluation.md | 69 +++-- docs/docs/user_management/adding_users.md | 2 +- docs/docusaurus.config.js | 21 +- docs/sidebars.js | 3 +- docs/src/pages/index.module.css | 2 +- 59 files changed, 2488 insertions(+), 1273 deletions(-) diff --git a/docs/docs/about/_category_.yml b/docs/docs/about/_category_.yml index 0383ea2d31..8fd45c2d89 100644 --- a/docs/docs/about/_category_.yml +++ b/docs/docs/about/_category_.yml @@ -1,2 +1,2 @@ label: About Minder -position: 100 \ No newline at end of file +position: 100 diff --git a/docs/docs/about/changelog.md b/docs/docs/about/changelog.md index e42519f8a5..ec85fd9d87 100644 --- a/docs/docs/about/changelog.md +++ b/docs/docs/about/changelog.md @@ -5,37 +5,51 @@ sidebar_position: 30 # Changelog -* **Profile selectors** - Sep 9, 2024 - You can now specify which repositories a profile applies to using a Common Expression Language (CEL) grammar. - -* **Rule evaluation history** - Sep 4, 2024 - You can now see how your security rules have applied to your repositories, pull requests, and artifacts throughout time, in addition to their current state. - -* **User management** - Aug 5, 2024 - Minder organization administrators can now invite additional users to the organization, and can set users permissions. - -* **Manage all GitHub repositories** - Jul 17, 2024 - Minder can now (optionally) manage all repositories within a GitHub organization, including new repositories that are created. Administrators can continue to select individual repositories to manage. - -* **Built-in rules** - Apr 6, 2024 - Minder now includes all the rules in our [sample rules repository](https://github.com/mindersec/minder-rules-and-profiles/) in your new projects automatically. This means that you do not need to clone that repository or add those rule types to make use of them. - - To use them, prefix the rule name as it exists in the sample rules repository with `stacklok/`. For example: - - ```yaml - --- - version: v1 - type: profile - name: uses-builtin-rules - context: - provider: github - repository: +- **Profile selectors** - Sep 9, 2024 + You can now specify which repositories a profile applies to using a Common + Expression Language (CEL) grammar. + +- **Rule evaluation history** - Sep 4, 2024 + You can now see how your security rules have applied to your repositories, + pull requests, and artifacts throughout time, in addition to their current + state. + +- **User management** - Aug 5, 2024 + Minder organization administrators can now invite additional users to the + organization, and can set users permissions. + +- **Manage all GitHub repositories** - Jul 17, 2024 + Minder can now (optionally) manage all repositories within a GitHub + organization, including new repositories that are created. Administrators can + continue to select individual repositories to manage. + +- **Built-in rules** - Apr 6, 2024 + Minder now includes all the rules in our + [sample rules repository](https://github.com/mindersec/minder-rules-and-profiles/) + in your new projects automatically. This means that you do not need to clone + that repository or add those rule types to make use of them. + + To use them, prefix the rule name as it exists in the sample rules repository + with `stacklok/`. For example: + + ```yaml + --- + version: v1 + type: profile + name: uses-builtin-rules + context: + provider: github + repository: - type: stacklok/secret_scanning def: enabled: true - ``` + ``` - You can still define custom rules, or continue to use the rules that exist in the [sample rules repository](https://github.com/mindersec/minder-rules-and-profiles). + You can still define custom rules, or continue to use the rules that exist in + the + [sample rules repository](https://github.com/mindersec/minder-rules-and-profiles). -* **User roles** - Jan 30, 2024 - You can now provide access control for users (eg: administrator, editor, viewer) in your project using [built-in roles](../user_management/user_roles.md). +- **User roles** - Jan 30, 2024 + You can now provide access control for users (eg: administrator, editor, + viewer) in your project using + [built-in roles](../user_management/user_roles.md). diff --git a/docs/docs/about/contributing.md b/docs/docs/about/contributing.md index a5430e8aa7..7cfb29af2a 100644 --- a/docs/docs/about/contributing.md +++ b/docs/docs/about/contributing.md @@ -4,17 +4,35 @@ sidebar_position: 80 --- # Contributing to Minder -Minder is an open-source project, and we welcome contributions from the community. There are several ways to contribute to Minder, including reporting bugs, suggesting new features, and submitting pull requests with code changes. + +Minder is an open-source project, and we welcome contributions from the +community. There are several ways to contribute to Minder, including reporting +bugs, suggesting new features, and submitting pull requests with code changes. ## Reporting Security Vulnerabilities -If you think you have found a security vulnerability in Minder please DO NOT disclose it publicly until we’ve had a chance to fix it. Please don’t report security vulnerabilities using GitHub issues; instead, please follow this [process](https://github.com/mindersec/minder/blob/main/SECURITY.md). + +If you think you have found a security vulnerability in Minder please DO NOT +disclose it publicly until we’ve had a chance to fix it. Please don’t report +security vulnerabilities using GitHub issues; instead, please follow this +[process](https://github.com/mindersec/minder/blob/main/SECURITY.md). ## Creating GitHub issues -GitHub issues are used to track feature request and bug reports. If you have a general usage question, please ask in [Minder's discussion forum](https://discord.com/invite/RkzVuTp3WK). If you are reporting a bug or requesting a feature, you can create a new issue in the [Minder GitHub repository](https://github.com/mindersec/minder/issues). + +GitHub issues are used to track feature request and bug reports. If you have a +general usage question, please ask in +[Minder's discussion forum](https://discord.com/invite/RkzVuTp3WK). If you are +reporting a bug or requesting a feature, you can create a new issue in the +[Minder GitHub repository](https://github.com/mindersec/minder/issues). ## Contributing code -If you've found an issue you'd like to work on, you can contribute code to Minder by submitting a pull request. Before you submit a pull request, please review the [Pull request process](https://github.com/mindersec/minder/blob/main/CONTRIBUTING.md#pull-request-process). + +If you've found an issue you'd like to work on, you can contribute code to +Minder by submitting a pull request. Before you submit a pull request, please +review the +[Pull request process](https://github.com/mindersec/minder/blob/main/CONTRIBUTING.md#pull-request-process). Thank you for taking the time to contribute to Minder! -The full guide to contributing is available in our [Contributor Guidelines](https://github.com/mindersec/minder/blob/main/CONTRIBUTING.md) in the Minder open-source repository. \ No newline at end of file +The full guide to contributing is available in our +[Contributor Guidelines](https://github.com/mindersec/minder/blob/main/CONTRIBUTING.md) +in the Minder open-source repository. diff --git a/docs/docs/about/roadmap.md b/docs/docs/about/roadmap.md index 4ab326cdd5..c6987b96de 100644 --- a/docs/docs/about/roadmap.md +++ b/docs/docs/about/roadmap.md @@ -4,38 +4,79 @@ sidebar_position: 70 --- # Roadmap + ## About this roadmap -This roadmap should serve as a reference point for Minder users and community members to understand where the project is heading. The roadmap is where you can learn about what features we're working on, what stage they're in, and when we expect to bring them to you. Priorities and requirements may change based on community feedback, roadblocks encountered, community contributions, and other factors. If you depend on a specific item, we encourage you to reach out to Stacklok to get updated status information, or help us deliver that feature by contributing to Minder. +This roadmap should serve as a reference point for Minder users and community +members to understand where the project is heading. The roadmap is where you can +learn about what features we're working on, what stage they're in, and when we +expect to bring them to you. Priorities and requirements may change based on +community feedback, roadblocks encountered, community contributions, and other +factors. If you depend on a specific item, we encourage you to reach out to +Stacklok to get updated status information, or help us deliver that feature by +contributing to Minder. ## How to contribute -Have any questions or comments about items on the Minder roadmap? Share your feedback via [Minder GitHub Discussions](https://github.com/mindersec/minder/discussions). +Have any questions or comments about items on the Minder roadmap? Share your +feedback via +[Minder GitHub Discussions](https://github.com/mindersec/minder/discussions). _Last updated: June 2024_ ## In progress -* **Improved information about alerts:** Improve the verbiage and explanation about the state of rule evaluations, and how you can remediate the problems. -* **Enforce license information for dependencies:** Ensure that dependencies in your repositories use licenses that you approve. -* **Create policy to manage licenses in PRs:** Add a rule type to block and/or add comments to pull requests based on the licenses of the dependencies they import. -* **Generalized "provider" support:** Improve the ability for developers to add integration points to Minder to provide custom information about entities in their software development lifecycle. +- **Improved information about alerts:** Improve the verbiage and explanation + about the state of rule evaluations, and how you can remediate the problems. +- **Enforce license information for dependencies:** Ensure that dependencies in + your repositories use licenses that you approve. +- **Create policy to manage licenses in PRs:** Add a rule type to block and/or + add comments to pull requests based on the licenses of the dependencies they + import. +- **Generalized "provider" support:** Improve the ability for developers to add + integration points to Minder to provide custom information about entities in + their software development lifecycle. ## Next -* **Report CVEs, Stacklok Insight scores, and license info for ingested SBOMs:** Ingest SBOMS and identify dependencies; show CVEs, Stacklok Insight scores, and license information including any changes over time. -* **Block PRs based on Stacklok Insight scores:** In addition to adding comments to pull requests (as is currently available), add the option to block pull requests as a policy remediation. -* **Policy events:** Provide information about rule evaluation as it changes, and historical rule evaluation. -* **Generate SBOMs:** Enable users to automatically create and sign SBOMs. +- **Report CVEs, Stacklok Insight scores, and license info for ingested SBOMs:** + Ingest SBOMS and identify dependencies; show CVEs, Stacklok Insight scores, + and license information including any changes over time. +- **Block PRs based on Stacklok Insight scores:** In addition to adding comments + to pull requests (as is currently available), add the option to block pull + requests as a policy remediation. +- **Policy events:** Provide information about rule evaluation as it changes, + and historical rule evaluation. +- **Generate SBOMs:** Enable users to automatically create and sign SBOMs. ## Future considerations -* **Project hierarchies:** Enable users to create nested projects and group repositories within those projects. Projects will inherit profile rules in order to simplify profile and policy management. -* **Automate the generation and signing of SLSA provenance statements:** Enable users to generate SLSA provenance statements (e.g. through SLSA GitHub generator) and sign them with Sigstore. -* **Register GitLab and Bitbucket repositories:** In addition to managing GitHub repositories, enable users to manage configuration and policy for other source control providers. -* **Export a Minder 'badge/certification' that shows what practices a project followed:** Create a badge that OSS maintainers and enterprise developers can create and share with others that asserts the Minder practices and policies their projects follow. -* **Temporary permissions to providers vs. long-running:** Policy remediation currently requires long-running permissions to providers such as GitHub; provide the option to enable temporary permissions. -* **Create PRs for dependency updates:** As a policy autoremediation option, enable Minder to automatically create pull requests to update dependencies based on vulnerabilities, Stacklok Insight scores, or license changes. -* **Drive policy through git (config management):** Enable users to dynamically create and maintain policies from other sources, e.g. Git, allowing for easier policy maintenance and the ability to manage policies through GitOps workflows. -* **Integrations with additional OSS and commercial tools:** Integrate with tools that run code and secrets scanning (eg Snyk), and behavior analysis (eg [OSSF Package Analysis tool](https://github.com/ossf/package-analysis)). -* **Help package authors improve Stacklok Insight Scores:** Provide guidance and/or policy to improve key Stacklok Insight Store metrics (open issues, active contributors). +- **Project hierarchies:** Enable users to create nested projects and group + repositories within those projects. Projects will inherit profile rules in + order to simplify profile and policy management. +- **Automate the generation and signing of SLSA provenance statements:** Enable + users to generate SLSA provenance statements (e.g. through SLSA GitHub + generator) and sign them with Sigstore. +- **Register GitLab and Bitbucket repositories:** In addition to managing GitHub + repositories, enable users to manage configuration and policy for other source + control providers. +- **Export a Minder 'badge/certification' that shows what practices a project + followed:** Create a badge that OSS maintainers and enterprise developers can + create and share with others that asserts the Minder practices and policies + their projects follow. +- **Temporary permissions to providers vs. long-running:** Policy remediation + currently requires long-running permissions to providers such as GitHub; + provide the option to enable temporary permissions. +- **Create PRs for dependency updates:** As a policy autoremediation option, + enable Minder to automatically create pull requests to update dependencies + based on vulnerabilities, Stacklok Insight scores, or license changes. +- **Drive policy through git (config management):** Enable users to dynamically + create and maintain policies from other sources, e.g. Git, allowing for easier + policy maintenance and the ability to manage policies through GitOps + workflows. +- **Integrations with additional OSS and commercial tools:** Integrate with + tools that run code and secrets scanning (eg Snyk), and behavior analysis (eg + [OSSF Package Analysis tool](https://github.com/ossf/package-analysis)). +- **Help package authors improve Stacklok Insight Scores:** Provide guidance + and/or policy to improve key Stacklok Insight Store metrics (open issues, + active contributors). diff --git a/docs/docs/developer_guide/_category_.yml b/docs/docs/developer_guide/_category_.yml index 76271c02c9..6a22d01ab3 100644 --- a/docs/docs/developer_guide/_category_.yml +++ b/docs/docs/developer_guide/_category_.yml @@ -1,2 +1,2 @@ label: Developer Guide -position: 50 \ No newline at end of file +position: 50 diff --git a/docs/docs/developer_guide/feature_flags.md b/docs/docs/developer_guide/feature_flags.md index fde6f367a9..b3dac26338 100644 --- a/docs/docs/developer_guide/feature_flags.md +++ b/docs/docs/developer_guide/feature_flags.md @@ -5,44 +5,93 @@ sidebar_position: 20 # Using Feature Flags -Minder is using [OpenFeature](https://openfeature.dev/) for feature flags. For more complex configuration, refer to that documentation. With that said, our goals are to allow for _simple, straightforward_ usage of feature flags to **allow merging code which is complete before the entire feature is complete**. +Minder is using [OpenFeature](https://openfeature.dev/) for feature flags. For +more complex configuration, refer to that documentation. With that said, our +goals are to allow for _simple, straightforward_ usage of feature flags to +**allow merging code which is complete before the entire feature is complete**. ## When to use feature flags Appropriate usages of feature flags: -* **Stage Changes**. Use a feature flag to (for example) add the ability to write values in one PR, and the ability to operate on them in another PR. By putting all the functionality behind a feature flag, it can be released all at once (when the documentation is complete). Depending on the functionality, this may also be used to achieve a **staged rollout** across a larger population of users, starting with people willing to beta-test the feature. - -* **Kill Switch**. For features which introduce new load (e.g. 10x GitHub API token usage) or new access patterns (e.g. change message durability), feature flags can provide a quick way to be able to enable or revert changes without needing to build and push a new binary or config option (particularly if other code has changed in the meantime). In this case, feature flags provide a consistent way of managing configuration as an alternative to `internal/config/server`. Note that _feature flags_ affect a particular invocation (based on the user or project in question), while _config_ generally affects all behavior of the server. - -* **Feature acceptance testing** (A/B testing). When running Minder as a service, the Stacklok team may want to perform large-scale evaluation of whether a feature is useful to end-users. Feature flags can allow comparing the usage of two groups with and without the feature enabled. +- **Stage Changes**. Use a feature flag to (for example) add the ability to + write values in one PR, and the ability to operate on them in another PR. By + putting all the functionality behind a feature flag, it can be released all at + once (when the documentation is complete). Depending on the functionality, + this may also be used to achieve a **staged rollout** across a larger + population of users, starting with people willing to beta-test the feature. + +- **Kill Switch**. For features which introduce new load (e.g. 10x GitHub API + token usage) or new access patterns (e.g. change message durability), feature + flags can provide a quick way to be able to enable or revert changes without + needing to build and push a new binary or config option (particularly if other + code has changed in the meantime). In this case, feature flags provide a + consistent way of managing configuration as an alternative to + `internal/config/server`. Note that _feature flags_ affect a particular + invocation (based on the user or project in question), while _config_ + generally affects all behavior of the server. + +- **Feature acceptance testing** (A/B testing). When running Minder as a + service, the Stacklok team may want to perform large-scale evaluation of + whether a feature is useful to end-users. Feature flags can allow comparing + the usage of two groups with and without the feature enabled. ### Inappropriate Use Of Feature Flags -We expect that feature flags will generally be short-lived (a few months in most cases). There are costs (testing, maintenance, complexity, and general opportunity costs) to maintaining two code paths, so we aim to retire feature flags once the feature is considered "stable". Here are some examples of alternative mechanisms to use for long-term behavior changes: +We expect that feature flags will generally be short-lived (a few months in most +cases). There are costs (testing, maintenance, complexity, and general +opportunity costs) to maintaining two code paths, so we aim to retire feature +flags once the feature is considered "stable". Here are some examples of +alternative mechanisms to use for long-term behavior changes: -* **Server Configuration**. See [`internal/config/server`](https://github.com/mindersec/minder/tree/main/internal/config/server) for long-term options that should be on or off at server startup and don't need to change based on the invocation. +- **Server Configuration**. See + [`internal/config/server`](https://github.com/mindersec/minder/tree/main/internal/config/server) + for long-term options that should be on or off at server startup and don't + need to change based on the invocation. -* **Entitlements**. See [`internal/projects/features`](https://github.com/mindersec/minder/tree/main/internal/projects/features) for functionality that should be able to be turned on or off on a per-project basis (for example, for paid customers). +- **Entitlements**. See + [`internal/projects/features`](https://github.com/mindersec/minder/tree/main/internal/projects/features) + for functionality that should be able to be turned on or off on a per-project + basis (for example, for paid customers). ## How to Use Feature Flags -If you're working on a new Minder feature and want to merge it incrementally, check out [this code (linked to commit)](https://github.com/mindersec/minder/blob/d8f7d5709540bd33a2200adc2dbd330bbeceae86/internal/controlplane/handlers_authz.go#L222) for an example. The process is basically: +If you're working on a new Minder feature and want to merge it incrementally, +check out +[this code (linked to commit)](https://github.com/mindersec/minder/blob/d8f7d5709540bd33a2200adc2dbd330bbeceae86/internal/controlplane/handlers_authz.go#L222) +for an example. The process is basically: -1. Add a feature flag declaration to [`internal/flags/constants.go`](https://github.com/mindersec/minder/blob/main/internal/flags/constants.go) +1. Add a feature flag declaration to + [`internal/flags/constants.go`](https://github.com/mindersec/minder/blob/main/internal/flags/constants.go) -1. At the call site(s), put the new functionality behind `if flags.Bool(ctx, s.featureFlags, flags.MyFlagName) {...` +1. At the call site(s), put the new functionality behind + `if flags.Bool(ctx, s.featureFlags, flags.MyFlagName) {...` -1. You can use the [`flags.FakeClient`](https://github.com/mindersec/minder/blob/main/internal/flags/test_client.go) in tests to test the new code path as well as the old one. +1. You can use the + [`flags.FakeClient`](https://github.com/mindersec/minder/blob/main/internal/flags/test_client.go) + in tests to test the new code path as well as the old one. -Using `flags.Bool` from our own repo will enable a couple bits of default behavior over OpenFeature: +Using `flags.Bool` from our own repo will enable a couple bits of default +behavior over OpenFeature: -* We enforce that the default value of the flag is "off", so you can't end up with the confusing `disable_feature=false` in a config. -* We extract the user, project, and provider from `ctx`, so you don't need to. -* Eventually, we'll also record the flag settings in our telemetry records (WIP) +- We enforce that the default value of the flag is "off", so you can't end up + with the confusing `disable_feature=false` in a config. +- We extract the user, project, and provider from `ctx`, so you don't need to. +- Eventually, we'll also record the flag settings in our telemetry records (WIP) ## Using Flags During Development -You can create a `flags-config.yaml` in the root Minder directory when running with `make run-docker`, and the file (and future changes) will be mapped into the Minder container, so you can make changes live. The `flags-config.yaml` uses the [GoFeatureFlag format](https://gofeatureflag.org/docs/configure_flag/flag_format), and is in the repo's `.gitignore`, so you don't need to worry about accidentally checking it in. Note that the Minder server currently rechecks the flag configuration once a minute, so it may take a minute or two for flags changes to be visible. - -When deploying as a Helm chart, you can create a ConfigMap named `minder-flags` containing a key `flags-config.yaml`, and it will be mounted into the container. Again, changes to the `minder-flags` ConfigMap will be updated in the Minder server within about 2 minutes of update. +You can create a `flags-config.yaml` in the root Minder directory when running +with `make run-docker`, and the file (and future changes) will be mapped into +the Minder container, so you can make changes live. The `flags-config.yaml` uses +the +[GoFeatureFlag format](https://gofeatureflag.org/docs/configure_flag/flag_format), +and is in the repo's `.gitignore`, so you don't need to worry about accidentally +checking it in. Note that the Minder server currently rechecks the flag +configuration once a minute, so it may take a minute or two for flags changes to +be visible. + +When deploying as a Helm chart, you can create a ConfigMap named `minder-flags` +containing a key `flags-config.yaml`, and it will be mounted into the container. +Again, changes to the `minder-flags` ConfigMap will be updated in the Minder +server within about 2 minutes of update. diff --git a/docs/docs/developer_guide/get-hacking.md b/docs/docs/developer_guide/get-hacking.md index 8151c66b4e..913cc11176 100644 --- a/docs/docs/developer_guide/get-hacking.md +++ b/docs/docs/developer_guide/get-hacking.md @@ -6,23 +6,32 @@ sidebar_position: 1 # Get Hacking ## Run Minder -Follow the steps in the [Installing a Development version](./../run_minder_server/run_the_server.md) guide. -The application will be available on `https://localhost:8080` and gRPC on `https://localhost:8090`. +Follow the steps in the +[Installing a Development version](./../run_minder_server/run_the_server.md) +guide. + +The application will be available on `https://localhost:8080` and gRPC on +`https://localhost:8090`. + +When iterating, it can be helpful to only rebuild and reload the `minder` +container. You can do this with: -When iterating, it can be helpful to only rebuild and reload the `minder` container. You can do this with: ```bash make run-docker services=minder ``` ## Run the tests + ```bash make test ``` ## CLI -The CLI is available in the `cmd/cli` directory. You can also use the pre-built `minder` CLI with your new application; you'll need to set the `--grpc-host localhost --grpc-port 8090` arguments in either case. +The CLI is available in the `cmd/cli` directory. You can also use the pre-built +`minder` CLI with your new application; you'll need to set the +`--grpc-host localhost --grpc-port 8090` arguments in either case. ```bash go run cmd/cli/main.go --help @@ -30,15 +39,19 @@ go run cmd/cli/main.go --help ## APIs -The APIs are defined in protobuf [here](https://github.com/mindersec/minder/blob/main/proto/minder/v1/minder.proto). +The APIs are defined in protobuf +[here](https://github.com/mindersec/minder/blob/main/proto/minder/v1/minder.proto). -An OpenAPI / swagger spec is generated to [here](https://github.com/mindersec/minder/blob/main/pkg/api/openapi/proto/minder/v1/minder.swagger.json) +An OpenAPI / swagger spec is generated to +[here](https://github.com/mindersec/minder/blob/main/pkg/api/openapi/proto/minder/v1/minder.swagger.json) -It can be accessed over gRPC or HTTP using [gprc-gateway](https://grpc-ecosystem.github.io/grpc-gateway/). +It can be accessed over gRPC or HTTP using +[gprc-gateway](https://grpc-ecosystem.github.io/grpc-gateway/). ## How to generate protobuf stubs -We use [buf](https://buf.build/docs/) to generate the gRPC / HTTP stubs (both protobuf and openAPI). +We use [buf](https://buf.build/docs/) to generate the gRPC / HTTP stubs (both +protobuf and openAPI). To build the stubs, run: @@ -84,5 +97,6 @@ An example server configuration file is `config/server-config.yaml.example`. Most values should be quite self-explanatory. -Before running the app, please copy the content of `config/config.yaml.example` into `$PWD/config.yaml` file, -and `config/server-config.yaml.example` into `$PWD/server-config.yaml` file, and modify to use your own settings. +Before running the app, please copy the content of `config/config.yaml.example` +into `$PWD/config.yaml` file, and `config/server-config.yaml.example` into +`$PWD/server-config.yaml` file, and modify to use your own settings. diff --git a/docs/docs/getting_started/enroll_provider.md b/docs/docs/getting_started/enroll_provider.md index e715b85221..579bc43ab5 100644 --- a/docs/docs/getting_started/enroll_provider.md +++ b/docs/docs/getting_started/enroll_provider.md @@ -5,17 +5,23 @@ sidebar_position: 40 # Enrolling the GitHub Provider -Once you have authenticated to Minder, you'll need to enroll your GitHub credentials to allow Minder to manage your GitHub repositories. This allows Minder to inspect and manage your repository configuration. You will be prompted to grant Minder access. +Once you have authenticated to Minder, you'll need to enroll your GitHub +credentials to allow Minder to manage your GitHub repositories. This allows +Minder to inspect and manage your repository configuration. You will be prompted +to grant Minder access. -In the future, Minder will support other source control and artifact repositories, and you will be able to enroll credentials for those providers in the same manner. +In the future, Minder will support other source control and artifact +repositories, and you will be able to enroll credentials for those providers in +the same manner. -:::note -If you used the [minder `quickstart` command](quickstart), the GitHub Provider was enrolled as part of the quickstart, and you do not need to enroll a second time. -::: +:::note If you used the [minder `quickstart` command](quickstart), the GitHub +Provider was enrolled as part of the quickstart, and you do not need to enroll a +second time. ::: ## Prerequisites -Before you can enroll the GitHub Provider, you must [log in to Minder using the CLI](login). +Before you can enroll the GitHub Provider, you must +[log in to Minder using the CLI](login). ## Enrolling and granting access @@ -25,14 +31,23 @@ To enroll your GitHub credentials in your Minder account, run: minder provider enroll ``` -A browser session will open. If you are a member of multiple GitHub organizations, then you will be prompted which organization you want to enroll. You can select your personal account, or a GitHub organization that contains the repositories that you want to manage with Minder. +A browser session will open. If you are a member of multiple GitHub +organizations, then you will be prompted which organization you want to enroll. +You can select your personal account, or a GitHub organization that contains the +repositories that you want to manage with Minder. ![Selecting a GitHub organization](images/select-github-organization.png) -Then you will need to select which repositories you want to allow Minder to manage. You can select all repositories within your GitHub organization, or you can choose individual repositories. If you select individual repositories, they will not be visible within Minder, and you will not be able to [register them](register_repos). +Then you will need to select which repositories you want to allow Minder to +manage. You can select all repositories within your GitHub organization, or you +can choose individual repositories. If you select individual repositories, they +will not be visible within Minder, and you will not be able to +[register them](register_repos). ![Selecting GitHub repositories](images/select-repositories.png) You can change your repository selection within GitHub at any time. -Once you authorize Minder within GitHub, the browser window will close, and you will have enrolled the GitHub Provider. The `minder` CLI application will report the session is complete. +Once you authorize Minder within GitHub, the browser window will close, and you +will have enrolled the GitHub Provider. The `minder` CLI application will report +the session is complete. diff --git a/docs/docs/getting_started/first_profile.md b/docs/docs/getting_started/first_profile.md index 3760538de2..8cfb4882c4 100644 --- a/docs/docs/getting_started/first_profile.md +++ b/docs/docs/getting_started/first_profile.md @@ -5,32 +5,51 @@ sidebar_position: 60 # Creating your first profile -Once you have registered repositories, you can create a profile that specifies the common, consistent configuration that you expect your your repositories to comply with. +Once you have registered repositories, you can create a profile that specifies +the common, consistent configuration that you expect your your repositories to +comply with. ## Prerequisites -Before you can create a profile, you should [register repositories](register_repos). +Before you can create a profile, you should +[register repositories](register_repos). ## Creating a profile -A profile is composed of a set of one or more rule types, each of which scan for an individual piece of configuration within a repository. +A profile is composed of a set of one or more rule types, each of which scan for +an individual piece of configuration within a repository. -For example, you may have a profile that describes your organization's security best practices, and this profile may have two rule types: GitHub secret scanning should be enabled, and secret push protection should be enabled. +For example, you may have a profile that describes your organization's security +best practices, and this profile may have two rule types: GitHub secret scanning +should be enabled, and secret push protection should be enabled. -In this example, Minder will scan the repositories that you've registered and identify any repositories that do not have secret scanning enabled, and those that do not have secret push protection enabled. +In this example, Minder will scan the repositories that you've registered and +identify any repositories that do not have secret scanning enabled, and those +that do not have secret push protection enabled. ### Adding rule types -In Minder, the rule type configuration is completely flexible, and you can author them yourself. Because of this, your Minder organization does not have any rule types configured when you create it. You need to configure some, and you can upload some of Minder's already created rules from the [minder-rules-and-profiles repository](https://github.com/mindersec/minder-rules-and-profiles). +In Minder, the rule type configuration is completely flexible, and you can +author them yourself. Because of this, your Minder organization does not have +any rule types configured when you create it. You need to configure some, and +you can upload some of Minder's already created rules from the +[minder-rules-and-profiles repository](https://github.com/mindersec/minder-rules-and-profiles). -For example, to add a rule type that ensures that secret scanning is enabled, and one that ensures that secret push protection is enabled, you can download the [secret_scanning.yaml](https://github.com/mindersec/minder-rules-and-profiles/blob/main/rule-types/github/secret_scanning.yaml) and [secret_push_protection.yaml](https://github.com/mindersec/minder-rules-and-profiles/blob/main/rule-types/github/secret_push_protection.yaml) rule types. +For example, to add a rule type that ensures that secret scanning is enabled, +and one that ensures that secret push protection is enabled, you can download +the +[secret_scanning.yaml](https://github.com/mindersec/minder-rules-and-profiles/blob/main/rule-types/github/secret_scanning.yaml) +and +[secret_push_protection.yaml](https://github.com/mindersec/minder-rules-and-profiles/blob/main/rule-types/github/secret_push_protection.yaml) +rule types. ```bash curl -LO https://raw.githubusercontent.com/mindersec/minder-rules-and-profiles/main/rule-types/github/secret_scanning.yaml curl -LO https://raw.githubusercontent.com/mindersec/minder-rules-and-profiles/main/rule-types/github/secret_push_protection.yaml ``` -Once you've downloaded the rule type configuration from GitHub, you can upload them to your Minder organization. +Once you've downloaded the rule type configuration from GitHub, you can upload +them to your Minder organization. ```bash minder ruletype create -f secret_scanning.yaml @@ -39,11 +58,16 @@ minder ruletype create -f secret_push_protection.yaml ### Creating a profile -Once you have added the rule type definitions to Minder, you can create a profile that uses them to scan your repositories. +Once you have added the rule type definitions to Minder, you can create a +profile that uses them to scan your repositories. -Like rules, profiles are defined in YAML. They specify the rules that apply to your organization, whether you want to be alerted with GitHub Security Advisories, and whether you want Minder to try to automatically remediate problems when they're found. +Like rules, profiles are defined in YAML. They specify the rules that apply to +your organization, whether you want to be alerted with GitHub Security +Advisories, and whether you want Minder to try to automatically remediate +problems when they're found. -To create a profile that checks for secret scanning and secret push protection in your repositories, create a file called `my_profile.yaml`: +To create a profile that checks for secret scanning and secret push protection +in your repositories, create a file called `my_profile.yaml`: ```yaml --- @@ -52,8 +76,8 @@ type: profile name: my_profile context: provider: github -alert: "on" -remediate: "off" +alert: 'on' +remediate: 'off' repository: - type: secret_scanning def: @@ -69,14 +93,14 @@ Then upload the profile configuration to Minder: minder profile create -f my_profile.yaml ``` - - Check the status of the profile: + ``` minder profile status list --name my_profile ``` -If all registered repositories have secret scanning enabled, you will see the `OVERALL STATUS` is `Success`, otherwise the -overall status is `Failure`. + +If all registered repositories have secret scanning enabled, you will see the +`OVERALL STATUS` is `Success`, otherwise the overall status is `Failure`. ``` +--------------------------------------+------------+----------------+----------------------+ @@ -88,8 +112,8 @@ overall status is `Failure`. If secret scanning is not enabled, you will see `Failure` instead of `Success`. - See a detailed view of which repositories satisfy the secret scanning rule: + ``` minder profile status list --name my_profile --detailed ``` diff --git a/docs/docs/getting_started/install_cli.md b/docs/docs/getting_started/install_cli.md index 92c0a55594..3129b135a7 100644 --- a/docs/docs/getting_started/install_cli.md +++ b/docs/docs/getting_started/install_cli.md @@ -5,21 +5,27 @@ sidebar_position: 10 # Installing the Minder CLI -The open source Minder CLI can communicate with either [the free public instance provided by Stacklok](../../#minder-public-instance), or with a [self managed server](../run_minder_server/run_the_server). +The open source Minder CLI can communicate with either +[the free public instance provided by Stacklok](../../#minder-public-instance), +or with a [self managed server](../run_minder_server/run_the_server). -The `minder` CLI is built for `amd64` and `arm64` architectures on Windows, MacOS, and Linux. +The `minder` CLI is built for `amd64` and `arm64` architectures on Windows, +MacOS, and Linux. You can install `minder` using one of the following methods: ## macOS -The easiest way to install `minder` for macOS systems is through [Homebrew](https://brew.sh/): +The easiest way to install `minder` for macOS systems is through +[Homebrew](https://brew.sh/): ```bash brew install minder ``` -Alternatively, you can [download a `.tar.gz` release](https://github.com/mindersec/minder/releases) and unpack it with the following: +Alternatively, you can +[download a `.tar.gz` release](https://github.com/mindersec/minder/releases) and +unpack it with the following: ```bash tar -xzf minder_${RELEASE}_darwin_${ARCH}.tar.gz minder @@ -34,12 +40,17 @@ For Windows, the built-in `winget` tool is the easiest way to install `minder`: winget install stacklok.minder ``` -Alternatively, you can [download a zipfile containing the `minder` CLI](https://github.com/mindersec/minder/releases) and install the binary yourself. +Alternatively, you can +[download a zipfile containing the `minder` CLI](https://github.com/mindersec/minder/releases) +and install the binary yourself. ## Linux -We provide pre-built static binaries for Linux at: https://github.com/mindersec/minder/releases. +We provide pre-built static binaries for Linux at: +https://github.com/mindersec/minder/releases. ## Building from source -You can also build the `minder` CLI from source using `go install github.com/mindersec/minder/cmd/cli@latest`, or by [following the build instructions in the repository](https://github.com/mindersec/minder#build-from-source). +You can also build the `minder` CLI from source using +`go install github.com/mindersec/minder/cmd/cli@latest`, or by +[following the build instructions in the repository](https://github.com/mindersec/minder#build-from-source). diff --git a/docs/docs/getting_started/login.md b/docs/docs/getting_started/login.md index 19aad8bb74..3397234592 100644 --- a/docs/docs/getting_started/login.md +++ b/docs/docs/getting_started/login.md @@ -5,18 +5,24 @@ sidebar_position: 20 # Logging in to Minder -To start using Minder, you must first log in. Logging in to a Minder server for the first time will create your account. +To start using Minder, you must first log in. Logging in to a Minder server for +the first time will create your account. -By default, the Minder CLI will log in to api.stacklok.com, a [free public instance provided by Stacklok](../../#minder-public-instance). If you have -your own hosted instance of Minder, you can log in to that server instead. +By default, the Minder CLI will log in to api.stacklok.com, a +[free public instance provided by Stacklok](../../#minder-public-instance). If +you have your own hosted instance of Minder, you can log in to that server +instead. ## Prerequisites -Before you can log in, you must have [installed the `minder` CLI application](install_cli). +Before you can log in, you must have +[installed the `minder` CLI application](install_cli). ## Logging in to the Minder Public Instance -The `minder` CLI defaults to using the hosted Stacklok public instance. When using the hosted environment, you do not need to set up a server; you simply log in to the Stacklok authentication instance using your GitHub credentials. +The `minder` CLI defaults to using the hosted Stacklok public instance. When +using the hosted environment, you do not need to set up a server; you simply log +in to the Stacklok authentication instance using your GitHub credentials. You can use the Stacklok public instance by running: @@ -24,11 +30,18 @@ You can use the Stacklok public instance by running: minder auth login ``` -A new browser window will open and you will be prompted to log in to the Stacklok instance using your GitHub credentials. Once you have logged in, proceed to enroll your credentials in Minder. +A new browser window will open and you will be prompted to log in to the +Stacklok instance using your GitHub credentials. Once you have logged in, +proceed to enroll your credentials in Minder. ## Logging in to your own Minder instance -To log in to a Minder server which you are running (self-hosted), you will need to know the URL of the Minder server and of the Keycloak instance used for authentication. If you are using [`docker compose` to run Minder on your local machine](../run_minder_server/run_the_server.md), these addresses will be `localhost:8090` for Minder and `localhost:8081` for Keycloak. +To log in to a Minder server which you are running (self-hosted), you will need +to know the URL of the Minder server and of the Keycloak instance used for +authentication. If you are using +[`docker compose` to run Minder on your local machine](../run_minder_server/run_the_server.md), +these addresses will be `localhost:8090` for Minder and `localhost:8081` for +Keycloak. You can log in to Minder using: @@ -36,12 +49,13 @@ You can log in to Minder using: minder auth login --grpc-host localhost --grpc-port 8090 --identity-url http://localhost:8081 ``` -Your web browser will be opened to log in to Keycloak, and then a banner will be printed an +Your web browser will be opened to log in to Keycloak, and then a banner will be +printed an ``` You have successfully logged in. - - Here are your details: + + Here are your details: ┌────────────────────────────────────────────────┐ │ Key Value │ @@ -51,4 +65,5 @@ Your web browser will be opened to log in to Keycloak, and then a banner will b Your access credentials have been saved to ~/.config/minder/credentials.json ``` -Once you have logged in, you'll want to [enroll your GitHub credentials in Minder so that it can act on your behalf](./enroll_provider.md). +Once you have logged in, you'll want to +[enroll your GitHub credentials in Minder so that it can act on your behalf](./enroll_provider.md). diff --git a/docs/docs/getting_started/quickstart.md b/docs/docs/getting_started/quickstart.md index 3fc5cb52ca..67aec8c87f 100644 --- a/docs/docs/getting_started/quickstart.md +++ b/docs/docs/getting_started/quickstart.md @@ -5,23 +5,33 @@ sidebar_position: 30 # Quickstart with Minder (< 1 min) -Minder provides a straightforward "quickstart" functionality that will create your first profile in Minder which ensures that GitHub secret scanning is enabled, and lets you select the GitHub repositories that you want this profile to apply to. +Minder provides a straightforward "quickstart" functionality that will create +your first profile in Minder which ensures that GitHub secret scanning is +enabled, and lets you select the GitHub repositories that you want this profile +to apply to. -The quickstart lets you get started with Minder, ensuring that secret scanning is enabled for your repositories in seconds. +The quickstart lets you get started with Minder, ensuring that secret scanning +is enabled for your repositories in seconds. ## Prerequisites -Before you can run the `quickstart` command, you must [log in to Minder using the CLI](login). +Before you can run the `quickstart` command, you must +[log in to Minder using the CLI](login). ## Quickstart -Now that you have installed the Minder CLI and have logged in to your Minder server, you can start using Minder! +Now that you have installed the Minder CLI and have logged in to your Minder +server, you can start using Minder! -Minder's `quickstart` command will simplify getting started managing GitHub repositories. It will perform three steps to help you get started: +Minder's `quickstart` command will simplify getting started managing GitHub +repositories. It will perform three steps to help you get started: -* [enroll the GitHub provider](enroll_provider), so that Minder can access your repositories -* [register repositories](register_repos), which selects which repositories you want to manage -* [add a rule type and create a profile](first_profile), which will detect repositories that don't have secret scanning enabled. +- [enroll the GitHub provider](enroll_provider), so that Minder can access your + repositories +- [register repositories](register_repos), which selects which repositories you + want to manage +- [add a rule type and create a profile](first_profile), which will detect + repositories that don't have secret scanning enabled. To get started, run: @@ -31,25 +41,42 @@ minder quickstart #### Enrolling the GitHub provider -This first step configures GitHub and produces an authentication token that allows Minder to inspect and manage your repository configuration. You will be prompted to grant Minder access. +This first step configures GitHub and produces an authentication token that +allows Minder to inspect and manage your repository configuration. You will be +prompted to grant Minder access. #### Registering repositories -This step allows you to select the repositories that you want Minder to manage. Every repository that you select will be scanned according to the profile that quickstart will set up (next). This profile will ensure that [secret scanning](https://docs.github.com/en/code-security/secret-scanning/about-secret-scanning) is enabled for these repositories. +This step allows you to select the repositories that you want Minder to manage. +Every repository that you select will be scanned according to the profile that +quickstart will set up (next). This profile will ensure that +[secret scanning](https://docs.github.com/en/code-security/secret-scanning/about-secret-scanning) +is enabled for these repositories. #### Create the `secret_scanning` rule type This step will upload the `secret_scanning` rule type to the server. -A _rule type_ is a definition of an individual security setting and how to evaluate it; for example, the `secret_scanning` rule type contains the logic to query GitHub and evaluate whether secret scanning is enabled for an individual repository. +A _rule type_ is a definition of an individual security setting and how to +evaluate it; for example, the `secret_scanning` rule type contains the logic to +query GitHub and evaluate whether secret scanning is enabled for an individual +repository. -Minder allows you to build custom rule types, or use [one of our pre-defined rule types](https://github.com/mindersec/minder-rules-and-profiles/pulls). But in either case, these rules must be uploaded to the Minder server before you can use them. +Minder allows you to build custom rule types, or use +[one of our pre-defined rule types](https://github.com/mindersec/minder-rules-and-profiles/pulls). +But in either case, these rules must be uploaded to the Minder server before you +can use them. #### Create the `quickstart` profile -This step will create a profile named `quickstart-profile` that contains the `secret_scanning` rule type. +This step will create a profile named `quickstart-profile` that contains the +`secret_scanning` rule type. -A _security profile_ is a definition of the rule types that you want to apply to your repositories. The `quickstart` command will create a profile with a single rule type, the `secret_scanning` rule type that it uploads. Once this has been created, Minder will scan all the repositories that you selected in step two to ensure that secret scanning is enabled for each of them. +A _security profile_ is a definition of the rule types that you want to apply to +your repositories. The `quickstart` command will create a profile with a single +rule type, the `secret_scanning` rule type that it uploads. Once this has been +created, Minder will scan all the repositories that you selected in step two to +ensure that secret scanning is enabled for each of them. Congratulations! 🎉 You've now successfully created your first profile! @@ -61,27 +88,42 @@ To see the status of your profile, run: minder profile status list --name quickstart-profile --detailed ``` -This command shows you the overall status of your profile, and how each rule evaluates for each of your registered repositories. +This command shows you the overall status of your profile, and how each rule +evaluates for each of your registered repositories. -You should see an entry for each repository that you registered. If the repository has secret scanning enabled, you should see a status of "Success"; if the repository does _not_ have secret scanning enabled, you should see a status of "Failure". +You should see an entry for each repository that you registered. If the +repository has secret scanning enabled, you should see a status of "Success"; if +the repository does _not_ have secret scanning enabled, you should see a status +of "Failure". ## What's next? There's a lot more to Minder than just secret scanning! -Now that you have everything set up, you can continue to run `minder` commands against the public instance of Minder -where you can manage your registered repositories, create profiles, rules and much more, so you can ensure your repositories are -configured consistently and securely. +Now that you have everything set up, you can continue to run `minder` commands +against the public instance of Minder where you can manage your registered +repositories, create profiles, rules and much more, so you can ensure your +repositories are configured consistently and securely. -* [Register more repositories](register_repos) to take advantage of Minder for more of your organization -* [Add additional rules and profiles](first_profile) to define your full security profile for your organization; you can see all of Minder's ready-to-use rules and example profiles [on GitHub](https://github.com/mindersec/minder-rules-and-profiles). +- [Register more repositories](register_repos) to take advantage of Minder for + more of your organization +- [Add additional rules and profiles](first_profile) to define your full + security profile for your organization; you can see all of Minder's + ready-to-use rules and example profiles + [on GitHub](https://github.com/mindersec/minder-rules-and-profiles). -In case there's something you don't find there yet, Minder is designed to be extensible. This allows for users to create their own custom rule types and profiles and ensure the specifics of their security posture are attested to. +In case there's something you don't find there yet, Minder is designed to be +extensible. This allows for users to create their own custom rule types and +profiles and ensure the specifics of their security posture are attested to. ## More information For more information about `minder`, see: -* `minder` CLI commands - [Docs](https://minder-docs.stacklok.dev/ref/cli/minder). -* `minder` REST API Documentation - [Docs](https://minder-docs.stacklok.dev/ref/api). -* `minder` rules and profiles maintained by Minder's team - [GitHub](https://github.com/mindersec/minder-rules-and-profiles). -* Minder documentation - [Docs](https://minder-docs.stacklok.dev). + +- `minder` CLI commands - + [Docs](https://minder-docs.stacklok.dev/ref/cli/minder). +- `minder` REST API Documentation - + [Docs](https://minder-docs.stacklok.dev/ref/api). +- `minder` rules and profiles maintained by Minder's team - + [GitHub](https://github.com/mindersec/minder-rules-and-profiles). +- Minder documentation - [Docs](https://minder-docs.stacklok.dev). diff --git a/docs/docs/getting_started/register_repos.md b/docs/docs/getting_started/register_repos.md index 920a99f61b..199c94b4c7 100644 --- a/docs/docs/getting_started/register_repos.md +++ b/docs/docs/getting_started/register_repos.md @@ -3,32 +3,43 @@ title: Registering repositories sidebar_position: 50 --- -Once you have enrolled the GitHub Provider, you can register your GitHub repositories with your Minder organization. This will define the repositories that your security profile will apply to. +Once you have enrolled the GitHub Provider, you can register your GitHub +repositories with your Minder organization. This will define the repositories +that your security profile will apply to. ## Prerequisites -Before you can register a repository, you must [enroll the GitHub Provider](enroll_provider). +Before you can register a repository, you must +[enroll the GitHub Provider](enroll_provider). ## Register repositories -Once you have enrolled the GitHub Provider, you can register repositories that you granted Minder access to within GitHub. +Once you have enrolled the GitHub Provider, you can register repositories that +you granted Minder access to within GitHub. -To get a list of repositories, and select them using a menu in Minder's text user interface, run: +To get a list of repositories, and select them using a menu in Minder's text +user interface, run: ```bash minder repo register ``` -You can also register an individual repository by name, or a set of repositories, comma-separated. For example: +You can also register an individual repository by name, or a set of +repositories, comma-separated. For example: ```bash minder repo register --name "owner/repo1,owner/repo2" ``` -After registering repositories, Minder will begin applying your existing profiles to those repositories and will identify repositories that are out of compliance with your security profiles. +After registering repositories, Minder will begin applying your existing +profiles to those repositories and will identify repositories that are out of +compliance with your security profiles. -In addition, Minder will set up a webhook in each repository that was registered. This allows Minder to identify when configuration changes are made to your repositories and re-scan them for compliance with your profiles. +In addition, Minder will set up a webhook in each repository that was +registered. This allows Minder to identify when configuration changes are made +to your repositories and re-scan them for compliance with your profiles. ## More information -For more information about repository registration, see the [additional documentation in "How Minder works"](../understand/repository_registration). +For more information about repository registration, see the +[additional documentation in "How Minder works"](../understand/repository_registration). diff --git a/docs/docs/getting_started/remediations.md b/docs/docs/getting_started/remediations.md index 4a9b8d4627..59719c1087 100644 --- a/docs/docs/getting_started/remediations.md +++ b/docs/docs/getting_started/remediations.md @@ -5,19 +5,30 @@ sidebar_position: 80 # Automatic remediation with Minder -After you've [created a profile](first_profile), you can [view the status](viewing_status) of your security profile, and you can optionally enable alerts through GitHub Security Advisories. But Minder can also automatically remediate your profile, which means that when it detects a repository that is not in compliance with your profile, Minder can attempt to remediate it, bringing it back into compliance. +After you've [created a profile](first_profile), you can +[view the status](viewing_status) of your security profile, and you can +optionally enable alerts through GitHub Security Advisories. But Minder can also +automatically remediate your profile, which means that when it detects a +repository that is not in compliance with your profile, Minder can attempt to +remediate it, bringing it back into compliance. ## Prerequisites -Before you can enable automatic remediations, you need to [add rule types](first_profile#adding-rule-types). +Before you can enable automatic remediations, you need to +[add rule types](first_profile#adding-rule-types). ## Enabling automatic remediation -If you added the `secret_scanning` and `secret_push_protection` rules when you [created your first profile](first_profile), then you can update your profile to turn automatic remediation on. When you do this, Minder will identify and repository that doesn't have secret scanning or secret push protection turned on, and will turn it on for you. +If you added the `secret_scanning` and `secret_push_protection` rules when you +[created your first profile](first_profile), then you can update your profile to +turn automatic remediation on. When you do this, Minder will identify and +repository that doesn't have secret scanning or secret push protection turned +on, and will turn it on for you. ## Creating a profile with `remediate: on` -To create a profile that has automatic remediation turned on for `secret_scanning` and `secret_push_protection`, update your `my_profile.yaml`: +To create a profile that has automatic remediation turned on for +`secret_scanning` and `secret_push_protection`, update your `my_profile.yaml`: ```yaml --- @@ -26,8 +37,8 @@ type: profile name: my_profile context: provider: github -alert: "on" -remediate: "on" +alert: 'on' +remediate: 'on' repository: - type: secret_scanning def: @@ -45,22 +56,33 @@ minder profile apply -f my_profile.yaml ## Automatic remediation in action -If you go to the GitHub repository settings for one of your registered repositories, then disable secret scanning, Minder will detect this change and automatically remediate it. +If you go to the GitHub repository settings for one of your registered +repositories, then disable secret scanning, Minder will detect this change and +automatically remediate it. -If you reload the page on GitHub, you should see that secret scanning has automatically been re-enabled. +If you reload the page on GitHub, you should see that secret scanning has +automatically been re-enabled. -Similarly, when Minder performs an automatic remediation, the profile status should move quickly through two states. +Similarly, when Minder performs an automatic remediation, the profile status +should move quickly through two states. -When remediation is on, the profile status should move quickly through three different states. After disabling secret scanning on a repository, check the status of the profile: +When remediation is on, the profile status should move quickly through three +different states. After disabling secret scanning on a repository, check the +status of the profile: ``` -minder profile status list --name my_profile +minder profile status list --name my_profile ``` -1. Immediately, you should see that the profile `STATUS` is set to `Failure`, and the `REMEDIATION` state is set to `Pending`. At this point, Minder will start the automatic remediation. -2. Once Minder has performed the remediation, the profile `STATUS` will remain at `Failure`, but the `REMEDIATION` state will change to `Success`. -3. After Minder has remediated the problem, it will evaluate the rule again. Once this completes, Minder will set the profile `STATUS` to `Success`. +1. Immediately, you should see that the profile `STATUS` is set to `Failure`, + and the `REMEDIATION` state is set to `Pending`. At this point, Minder will + start the automatic remediation. +2. Once Minder has performed the remediation, the profile `STATUS` will remain + at `Failure`, but the `REMEDIATION` state will change to `Success`. +3. After Minder has remediated the problem, it will evaluate the rule again. + Once this completes, Minder will set the profile `STATUS` to `Success`. # More information -For more information about automatic remediations, see the [additional documentation in "How Minder works"](../understand/remediations). +For more information about automatic remediations, see the +[additional documentation in "How Minder works"](../understand/remediations). diff --git a/docs/docs/getting_started/viewing_status.md b/docs/docs/getting_started/viewing_status.md index 2d649ddf21..7c56712224 100644 --- a/docs/docs/getting_started/viewing_status.md +++ b/docs/docs/getting_started/viewing_status.md @@ -5,37 +5,50 @@ sidebar_position: 70 # Viewing the status of your profile -When you have created a profile and registered repositories, Minder will evaluate your security profile against those repositories. Minder can report on the status, and can optionally alert you using GitHub Security Advisories. +When you have created a profile and registered repositories, Minder will +evaluate your security profile against those repositories. Minder can report on +the status, and can optionally alert you using GitHub Security Advisories. ## Prerequisites -Before you can view the status of your profile, you must [create a profile](first_profile). +Before you can view the status of your profile, you must +[create a profile](first_profile). ## Summary profile status -To view the summary status of your profile, use the `minder profile status list` command. If you have a profile named `my_profile`, run: +To view the summary status of your profile, use the `minder profile status list` +command. If you have a profile named `my_profile`, run: ```bash minder profile status list --name my_profile ``` -If all the registered repositories are in compliance with your profile, you will see the `OVERALL STATUS` column set to `Success`. If one or more repositories are not in compliance, the column will be set to `Failure`. +If all the registered repositories are in compliance with your profile, you will +see the `OVERALL STATUS` column set to `Success`. If one or more repositories +are not in compliance, the column will be set to `Failure`. -For example, the profile named `my_profile` expects repositories to have secret scanning enabled. If any repository did not have secret scanning enabled, then the output will look like: +For example, the profile named `my_profile` expects repositories to have secret +scanning enabled. If any repository did not have secret scanning enabled, then +the output will look like: ```yaml +--- +--------------------------------------+------------+----------------+----------------------+ -| ID | NAME | OVERALL STATUS | LAST UPDATED | +| ID | NAME | OVERALL STATUS | LAST +UPDATED | +--------------------------------------+------------+----------------+----------------------+ -| 1abcae55-5eb8-4d9e-847c-18e605fbc1cc | my_profile | Failed | 2023-11-06T17:42:04Z | +| 1abcae55-5eb8-4d9e-847c-18e605fbc1cc | my_profile | Failed | +2023-11-06T17:42:04Z | +--------------------------------------+------------+----------------+----------------------+ ``` -Use detailed status reporting to understand which repositories are not in compliance. +Use detailed status reporting to understand which repositories are not in +compliance. ## Detailed profile status -Detailed status will show each repository that is registered, along with the current evaluation status for each rule. +Detailed status will show each repository that is registered, along with the +current evaluation status for each rule. See a detailed view of which repositories satisfy the secret scanning rule: @@ -43,7 +56,12 @@ See a detailed view of which repositories satisfy the secret scanning rule: minder profile status list --name github-profile --detailed ``` -An example output for a profile that checks secret scanning and secret push protection, for an organization that has a single repository registered. In this example, the repository `example/demo_repo` has secret scanning enabled, which is indicated by the `STATUS` column set to `Success`. However, that repository does not have secret push protection enabled, which is indicated by the `STATUS` column set to `Failure`. +An example output for a profile that checks secret scanning and secret push +protection, for an organization that has a single repository registered. In this +example, the repository `example/demo_repo` has secret scanning enabled, which +is indicated by the `STATUS` column set to `Success`. However, that repository +does not have secret push protection enabled, which is indicated by the `STATUS` +column set to `Failure`. ```yaml +--------------------------------------+------------------------+------------+---------+-------------+--------------------------------------+ @@ -65,10 +83,25 @@ An example output for a profile that checks secret scanning and secret push prot ## Alerts with GitHub Security Advisories -You can optionally get alerted with [GitHub Security Advisories](https://docs.github.com/en/code-security/security-advisories) when repositories are not in compliance with your security profiles. If you have configured your profile with `alerts: on`, then Minder will generate GitHub Security Advisories. - -For example, if you've [created a profile with `alerts: on`](first_profile) that looks for secret scanning to be enabled in your repository, then _disabling_ secret scanning in that repository should produce a GitHub Security Advisory. - -In this example, if you [disable secret scanning](https://docs.github.com/en/code-security/secret-scanning/configuring-secret-scanning-for-your-repositories) in one of your registered repositories, Minder will create a GitHub Security Advisory in that repository. To view that, navigate to the repository on GitHub, click on the Security tab and view the Security Advisories. There will be a new advisories named `minder: profile my_profile failed with rule secret_scanning`. - -To resolve this issue, you can [enable secret scanning](https://docs.github.com/en/code-security/secret-scanning/configuring-secret-scanning-for-your-repositories) in that repository. When you do this, the advisory will be deleted. If you go back to the Security Advisories page on that repository, you will see that the advisory that was created by Minder has been closed. +You can optionally get alerted with +[GitHub Security Advisories](https://docs.github.com/en/code-security/security-advisories) +when repositories are not in compliance with your security profiles. If you have +configured your profile with `alerts: on`, then Minder will generate GitHub +Security Advisories. + +For example, if you've [created a profile with `alerts: on`](first_profile) that +looks for secret scanning to be enabled in your repository, then _disabling_ +secret scanning in that repository should produce a GitHub Security Advisory. + +In this example, if you +[disable secret scanning](https://docs.github.com/en/code-security/secret-scanning/configuring-secret-scanning-for-your-repositories) +in one of your registered repositories, Minder will create a GitHub Security +Advisory in that repository. To view that, navigate to the repository on GitHub, +click on the Security tab and view the Security Advisories. There will be a new +advisories named `minder: profile my_profile failed with rule secret_scanning`. + +To resolve this issue, you can +[enable secret scanning](https://docs.github.com/en/code-security/secret-scanning/configuring-secret-scanning-for-your-repositories) +in that repository. When you do this, the advisory will be deleted. If you go +back to the Security Advisories page on that repository, you will see that the +advisory that was created by Minder has been closed. diff --git a/docs/docs/how-to/artifact_signatures.md b/docs/docs/how-to/artifact_signatures.md index 10a3dbb5b6..3119b6bfa3 100644 --- a/docs/docs/how-to/artifact_signatures.md +++ b/docs/docs/how-to/artifact_signatures.md @@ -6,8 +6,8 @@ sidebar_position: 55 # Check Artifact Provenance With Minder you can create rules that assert that artifacts built from your -repositories are built from trusted sources and using trusted workflows based -on their cryptographically signed provenance. +repositories are built from trusted sources and using trusted workflows based on +their cryptographically signed provenance. This is done by creating a profile which utilizes the `artifact_signature` `rule_type`. @@ -24,18 +24,21 @@ This is done by creating a profile which utilizes the `artifact_signature` ## Create the artifact provenance rule type -Fetch all the reference rules by cloning the [minder-rules-and-profiles repository](https://github.com/mindersec/minder-rules-and-profiles). +Fetch all the reference rules by cloning the +[minder-rules-and-profiles repository](https://github.com/mindersec/minder-rules-and-profiles). ``` git clone https://github.com/mindersec/minder-rules-and-profiles.git ``` In that directory you can find all the reference rules and profiles. + ``` cd minder-rules-and-profiles ``` Create the `artifact_signature` rule type in Minder: + ``` minder ruletype create -f rule-types/github/artifact_signature.yaml ``` @@ -44,15 +47,16 @@ minder ruletype create -f rule-types/github/artifact_signature.yaml Next, create a profile that applies the rule type to the appropriate artifact. -The artifacts are referred to by name and tag. If the name is not specified, -the rule will match any artifact name. The tag can be specified either as a list -of tags using the `tags` parameter or as a regular expression using the `tag_regex` -parameter. If both are empty, the rule will match any tag. It is an error to specify -both `tags` and `tag_regex`. +The artifacts are referred to by name and tag. If the name is not specified, the +rule will match any artifact name. The tag can be specified either as a list of +tags using the `tags` parameter or as a regular expression using the `tag_regex` +parameter. If both are empty, the rule will match any tag. It is an error to +specify both `tags` and `tag_regex`. -Create a new file called `profile-artifact-simple.yaml`. The following example would match a container -image named `good-repo-go` with the `latest` tag. The profile would pass for any artifact that -has a signature, regardless of who signed it. +Create a new file called `profile-artifact-simple.yaml`. The following example +would match a container image named `good-repo-go` with the `latest` tag. The +profile would pass for any artifact that has a signature, regardless of who +signed it. ```yaml --- @@ -73,23 +77,25 @@ artifact: ``` Create the profile in Minder: + ``` minder profile create -f profile-artifact-simple.yaml ``` -Once the profile is created, Minder will start checking the artifacts produced by the enrolled repositories -and the policy status will be updated accordingly. If the artifact is not matching the expected provenance -(for example someone pushes a new image to the registry without signing it), a -violation is presented via the profile status and an alert is raised. +Once the profile is created, Minder will start checking the artifacts produced +by the enrolled repositories and the policy status will be updated accordingly. +If the artifact is not matching the expected provenance (for example someone +pushes a new image to the registry without signing it), a violation is presented +via the profile status and an alert is raised. ## Define a more advanced profile that checks artifact provenance -As the next step, let's create a profile that checks the provenance of the artifact. -Create a new file called `profile-artifact-provenance.yaml`. +As the next step, let's create a profile that checks the provenance of the +artifact. Create a new file called `profile-artifact-provenance.yaml`. -The profile would pass only if the container was -built from the `main` branch of the `good-repo-go` repository, using the `build-image-signed-ghat.yml` -workflow using a hosted github runner. +The profile would pass only if the container was built from the `main` branch of +the `good-repo-go` repository, using the `build-image-signed-ghat.yml` workflow +using a hosted github runner. ```yaml --- @@ -115,14 +121,14 @@ artifact: ``` Create the profile in Minder: + ``` minder profile create -f profile-artifact-provenance.yaml ``` Once the profile is created, Minder will start checking the artifacts produced -by the enrolled repositories and the policy status will be updated -accordingly. If the artifact is not matching the expected provenance (for -example someone pushes a new image to the registry after having signed the -image with their personal account or the image is built from a different -workflow or a different branch), a violation is presented via the profile -status and an alert is raised. +by the enrolled repositories and the policy status will be updated accordingly. +If the artifact is not matching the expected provenance (for example someone +pushes a new image to the registry after having signed the image with their +personal account or the image is built from a different workflow or a different +branch), a violation is presented via the profile status and an alert is raised. diff --git a/docs/docs/how-to/create_profile.md b/docs/docs/how-to/create_profile.md index 2c9eb290dc..69a6594159 100644 --- a/docs/docs/how-to/create_profile.md +++ b/docs/docs/how-to/create_profile.md @@ -11,38 +11,43 @@ sidebar_position: 10 ## Use a reference rule -The first step to creating a profile is to create the rules that your profile will apply. +The first step to creating a profile is to create the rules that your profile +will apply. -The Minder team has provided several reference rules for common use cases. To get started quickly, create a rule from -the set of references. +The Minder team has provided several reference rules for common use cases. To +get started quickly, create a rule from the set of references. -Fetch all the reference rules by cloning the [minder-rules-and-profiles repository](https://github.com/mindersec/minder-rules-and-profiles). +Fetch all the reference rules by cloning the +[minder-rules-and-profiles repository](https://github.com/mindersec/minder-rules-and-profiles). ``` git clone https://github.com/mindersec/minder-rules-and-profiles.git ``` In that directory you can find all the reference rules and profiles. + ``` cd minder-rules-and-profiles ``` Create the `secret_scanning` rule type in Minder: + ``` minder ruletype create -f rule-types/github/secret_scanning.yaml ``` ## Write your own rule -This section describes how to write your own rule, using the existing rule `secret_scanning` as a reference. If you've -already created the `secret_scanning` rule, you may choose to skip this section. +This section describes how to write your own rule, using the existing rule +`secret_scanning` as a reference. If you've already created the +`secret_scanning` rule, you may choose to skip this section. Start by creating a rule that checks if secret scanning is enabled. Create a new file called `secret_scanning.yaml`. -Add some basic information about the rule to the new file, such as the version, type, name, context, description and -guidance. +Add some basic information about the rule to the new file, such as the version, +type, name, context, description and guidance. ```yaml --- @@ -62,26 +67,31 @@ guidance: | https://docs.github.com/en/github/administering-a-repository/about-secret-scanning ``` -Next, add the rule definition to the `secret_scanning.yaml` file. -Set `in_entity` to be `repository`, since secret scanning is enabled on the repository. +Next, add the rule definition to the `secret_scanning.yaml` file. Set +`in_entity` to be `repository`, since secret scanning is enabled on the +repository. ```yaml def: in_entity: repository ``` -Create a `rule_schema` defining a property describing whether secret scanning is enabled on a repository. +Create a `rule_schema` defining a property describing whether secret scanning is +enabled on a repository. + ```yaml def: # ... rule_schema: - properties: - enabled: - type: boolean - default: true + properties: + enabled: + type: boolean + default: true ``` -Set `ingest` to make a REST call to fetch information about each registered repository and parse the response as JSON. +Set `ingest` to make a REST call to fetch information about each registered +repository and parse the response as JSON. + ```yaml def: # ... @@ -92,11 +102,13 @@ def: # for each repository in the organization, we use a template that # will be evaluated for each repository. The structure to use is the # protobuf structure for the entity that is being evaluated. - endpoint: "/repos/{{.Entity.Owner}}/{{.Entity.Name}}" + endpoint: '/repos/{{.Entity.Owner}}/{{.Entity.Name}}' parse: json ``` -Configure `eval` to use `jq` to read the response from the REST call and determine if secret scanning is enabled. +Configure `eval` to use `jq` to read the response from the REST call and +determine if secret scanning is enabled. + ```yaml def: # ... @@ -108,12 +120,13 @@ def: def: '.security_and_analysis.secret_scanning.status == "enabled"' # profile points to the profile itself. profile: - def: ".enabled" + def: '.enabled' ``` Set up the remediation action that will be taken if this rule is not satisfied -(and the profile has turned on remediation). The remediation action in this case is to make a PATCH request to the -repository and enable secret scanning. +(and the profile has turned on remediation). The remediation action in this case +is to make a PATCH request to the repository and enable secret scanning. + ```yaml def: # ... @@ -121,23 +134,27 @@ def: type: rest rest: method: PATCH - endpoint: "/repos/{{.Entity.Owner}}/{{.Entity.Name}}" + endpoint: '/repos/{{.Entity.Owner}}/{{.Entity.Name}}' body: | { "security_and_analysis": {"secret_scanning": { "status": "enabled" } } } ``` -Define how users will be alerted if this rule is not satisfied. In this case a security advisory will be created in -any repository that does not satisfy this rule. +Define how users will be alerted if this rule is not satisfied. In this case a +security advisory will be created in any repository that does not satisfy this +rule. + ```yaml def: # ... alert: - type: security_advisory - security_advisory: - severity: "medium" + type: security_advisory + security_advisory: + severity: 'medium' ``` -Putting it all together, you get the following content in `secret_scanning.yaml`: +Putting it all together, you get the following content in +`secret_scanning.yaml`: + ```yaml --- version: v1 @@ -163,7 +180,7 @@ def: ingest: type: rest rest: - endpoint: "/repos/{{.Entity.Owner}}/{{.Entity.Name}}" + endpoint: '/repos/{{.Entity.Owner}}/{{.Entity.Name}}' parse: json eval: type: jq @@ -171,32 +188,36 @@ def: - ingested: def: '.security_and_analysis.secret_scanning.status == "enabled"' profile: - def: ".enabled" + def: '.enabled' remediate: type: rest rest: method: PATCH - endpoint: "/repos/{{.Entity.Owner}}/{{.Entity.Name}}" + endpoint: '/repos/{{.Entity.Owner}}/{{.Entity.Name}}' body: | { "security_and_analysis": {"secret_scanning": { "status": "enabled" } } } alert: type: security_advisory security_advisory: - severity: "medium" + severity: 'medium' ``` Finally, create the `secret_scanning` rule in Minder: + ``` minder ruletype create -f secret_scanning.yaml ``` ## Create a profile -Now that you've created a secret scanning rule, you can set up a profile that checks if secret scanning is enabled -in all your registered repositories. + +Now that you've created a secret scanning rule, you can set up a profile that +checks if secret scanning is enabled in all your registered repositories. Start by creating a file named `profile.yaml`. -Add some basic information about the profile to the new file, such as the version, type, name and context. +Add some basic information about the profile to the new file, such as the +version, type, name and context. + ```yaml version: v1 type: profile @@ -205,18 +226,22 @@ context: provider: github ``` -Turn on alerting, so that a security advisory will be created for any registered repository that has not enabled -secret scanning. +Turn on alerting, so that a security advisory will be created for any registered +repository that has not enabled secret scanning. + ```yaml -alert: "on" +alert: 'on' ``` -Turn on remediation, so that secret scanning will automatically be enabled for any registered repositories. +Turn on remediation, so that secret scanning will automatically be enabled for +any registered repositories. + ```yaml -remediate: "on" +remediate: 'on' ``` Register the secret scanning rule that you created in the previous step. + ```yaml repository: - type: secret_scanning @@ -232,98 +257,114 @@ type: profile name: my-first-profile context: provider: github -alert: "on" -remediate: "on" +alert: 'on' +remediate: 'on' repository: - type: secret_scanning - name: "secret_scanning_github" # Optional, as there aren't multiple rules - # of the same type under the entity - repository + name: + 'secret_scanning_github' # Optional, as there aren't multiple rules + # of the same type under the entity - repository def: enabled: true ``` Finally, create your profile in Minder: + ```bash minder profile create -f profile.yaml ``` -Check the status of your profile and see which repositories satisfy the rules by running: +Check the status of your profile and see which repositories satisfy the rules by +running: + ```bash minder profile status list --name my-first-profile --detailed ``` -At the moment, the `profile status list` with the `--detailed` flag lists all the repositories that match the rules. -To get a more detailed view of the profile status, use the `-o json` flag to get the output in JSON format and then -filter the output using `jq`. For example, to get all rules that pertain to the repository `minder` and have failed, -run the following command: +At the moment, the `profile status list` with the `--detailed` flag lists all +the repositories that match the rules. To get a more detailed view of the +profile status, use the `-o json` flag to get the output in JSON format and then +filter the output using `jq`. For example, to get all rules that pertain to the +repository `minder` and have failed, run the following command: + ```bash minder profile status list --name stacklok-remediate-profile -d -ojson 2>/dev/null | jq -C '.ruleEvaluationStatus | map(select(.entityInfo.repo_name == "minder" and .status == "failure"))' ``` ## Defining Rule Names in Profiles -In Minder profiles, rules are identified by their type and, optionally, a unique name. +In Minder profiles, rules are identified by their type and, optionally, a unique +name. ### Rule Types vs Rule Names -Rule types are mandatory and refer to the kind of rule being applied. Rule names, on the other hand, are optional -identifiers that become crucial when multiple rules of the same type exist under an entity. +Rule types are mandatory and refer to the kind of rule being applied. Rule +names, on the other hand, are optional identifiers that become crucial when +multiple rules of the same type exist under an entity. ```yaml repository: - type: secret_scanning - name: "secret_scanning_github" + name: 'secret_scanning_github' def: enabled: true ``` -In this example, `secret_scanning` is the rule type and `secret_scanning_github` is the rule name. +In this example, `secret_scanning` is the rule type and `secret_scanning_github` +is the rule name. ### When are Rule Names Mandatory? -If you're using multiple rules of the same type under an entity, each rule must have a unique name. This helps -distinguish between rules and understand their specific purpose. +If you're using multiple rules of the same type under an entity, each rule must +have a unique name. This helps distinguish between rules and understand their +specific purpose. ```yaml repository: - type: secret_scanning - name: "secret_scanning_github" + name: 'secret_scanning_github' def: enabled: true - type: secret_scanning - name: "secret_scanning_github_2" + name: 'secret_scanning_github_2' def: enabled: false ``` -Here, we have two rules of the same type `secret_scanning` under the `repository` entity. Each rule has a unique name. + +Here, we have two rules of the same type `secret_scanning` under the +`repository` entity. Each rule has a unique name. ### Uniqueness of Rule Names -No two rules, whether of the same type or different types, can have the same name under an entity. This avoids -confusion and ensures each rule can be individually managed. +No two rules, whether of the same type or different types, can have the same +name under an entity. This avoids confusion and ensures each rule can be +individually managed. ```yaml repository: # Would return an error while creating - type: secret_scanning - name: "protect_github" + name: 'protect_github' def: enabled: true - type: secret_push_protection - name: "protect_github" + name: 'protect_github' def: enabled: false ``` -In the above used example, even though the rules are of different types (`secret_scanning` and `secret_push_protection`), -Minder will return an error while creating this profile as rule names are same under the same entity. -You may use same rule names under different entities (repository, artifacts, etc.) -Rule name should not match any rule type, except its own rule type. If a rule name matches its own rule type, it should -not conflict with any other rule name under the same entity, including default rule names. Example: +In the above used example, even though the rules are of different types +(`secret_scanning` and `secret_push_protection`), Minder will return an error +while creating this profile as rule names are same under the same entity. You +may use same rule names under different entities (repository, artifacts, etc.) + +Rule name should not match any rule type, except its own rule type. If a rule +name matches its own rule type, it should not conflict with any other rule name +under the same entity, including default rule names. Example: ```yaml repository: # Would return an error while creating - type: dependabot_configured - name: "dependabot_configured" + name: 'dependabot_configured' def: package_ecosystem: gomod schedule_interval: daily @@ -335,20 +376,22 @@ repository: # Would return an error while creating apply_if_file: docs/package.json ``` -In the above used example, even though the rules names appear different visually, Minder will return an error while -creating this profile as the rule name for `npm` rule would be `dependabot_configured` internally, which is same as -the explicit name of the `gomod` rule. +In the above used example, even though the rules names appear different +visually, Minder will return an error while creating this profile as the rule +name for `npm` rule would be `dependabot_configured` internally, which is same +as the explicit name of the `gomod` rule. ### Example -Consider a profile with two `dependabot_configured` rules under the `repository` entity. The first rule has a unique -name, "Dependabot Configured for GoLang". The second rule doesn't have a name, which is acceptable as Minder would -add rule type as the default name for the rule. +Consider a profile with two `dependabot_configured` rules under the `repository` +entity. The first rule has a unique name, "Dependabot Configured for GoLang". +The second rule doesn't have a name, which is acceptable as Minder would add +rule type as the default name for the rule. ```yaml repository: - type: dependabot_configured - name: "Dependabot Configured for GoLang" + name: 'Dependabot Configured for GoLang' def: package_ecosystem: gomod schedule_interval: daily @@ -361,4 +404,5 @@ repository: ``` You can find the rule definitions used above and many profile examples at -[minder-rules-and-profiles](https://github.com/mindersec/minder-rules-and-profiles) repository. +[minder-rules-and-profiles](https://github.com/mindersec/minder-rules-and-profiles) +repository. diff --git a/docs/docs/how-to/create_project.md b/docs/docs/how-to/create_project.md index 3e8dc9c8d5..50af2902f7 100644 --- a/docs/docs/how-to/create_project.md +++ b/docs/docs/how-to/create_project.md @@ -21,9 +21,11 @@ project. ## Creating a New Project -To create a new project, enable a minder [GitHub application](../run_minder_server/config_provider.md) -on a GitHub organization or user account. If the GitHub App is installed on a GitHub organization -which is not already registered in Minder, Minder will create a new project to -manage those resources. Using [`minder provider enroll`](../ref/cli/minder_provider_enroll.md) within a +To create a new project, enable a minder +[GitHub application](../run_minder_server/config_provider.md) on a GitHub +organization or user account. If the GitHub App is installed on a GitHub +organization which is not already registered in Minder, Minder will create a new +project to manage those resources. Using +[`minder provider enroll`](../ref/cli/minder_provider_enroll.md) within a project to add a new GitHub provider will _not_ create a new project and will add the selected organization to an existing project. diff --git a/docs/docs/how-to/custom-rules.md b/docs/docs/how-to/custom-rules.md index b909c49795..6d497694ad 100644 --- a/docs/docs/how-to/custom-rules.md +++ b/docs/docs/how-to/custom-rules.md @@ -4,23 +4,36 @@ sidebar_position: 100 # Writing custom rule types -Minder's policy engine is flexible enough that you can write your own rule types to check for specific settings in your supply chain. This guide will walk you through the process of writing a custom rule type. +Minder's policy engine is flexible enough that you can write your own rule types +to check for specific settings in your supply chain. This guide will walk you +through the process of writing a custom rule type. ## Minder policies -Minder allows you to check and enforce that certain settings are set up for several stages in your supply chain. To configure those settings, you need to create a Profile. This profile is composed of several rules that represent the settings you want in your supply chain. These rules are actually instantiations of another handy object for Minder called Rule Types. These rule types define the nitty-gritty details of how the specific setting you care about will be checked, how you'll be alerted when something goes out of order, and how it will be automatically remediated. +Minder allows you to check and enforce that certain settings are set up for +several stages in your supply chain. To configure those settings, you need to +create a Profile. This profile is composed of several rules that represent the +settings you want in your supply chain. These rules are actually instantiations +of another handy object for Minder called Rule Types. These rule types define +the nitty-gritty details of how the specific setting you care about will be +checked, how you'll be alerted when something goes out of order, and how it will +be automatically remediated. -You can browse a curated collection of rule types in the [rules and profiles repository])(https://github.com/mindersec/minder-rules-and-profiles). +You can browse a curated collection of rule types in the [rules and profiles +repository])(https://github.com/mindersec/minder-rules-and-profiles). Some of the rules include: -* Verifying if you have GitHub’s secret scanning enabled -* Verifying if your artifacts are signed and verifiable on Sigstore -* Verifying that your branch protection settings are secure +- Verifying if you have GitHub’s secret scanning enabled +- Verifying if your artifacts are signed and verifiable on Sigstore +- Verifying that your branch protection settings are secure ## Rule Types -Rule types aren’t particularly complicated. They include the basic structure to get an observed state, evaluate the rule based on that observed state, do actions based on that state, and finally, give you some instructions in case you want to manage things manually. +Rule types aren’t particularly complicated. They include the basic structure to +get an observed state, evaluate the rule based on that observed state, do +actions based on that state, and finally, give you some instructions in case you +want to manage things manually. The Rule Type object in YAML looks as follows: @@ -44,25 +57,46 @@ def: The following are the components of a rule type: -* **Description**: What does the rule do? This is handy to browse through rule types when building a profile. -* **Guidance**: What do I do if this rule presents a “failure”? This is handy to inform folks of what to do in case they’re not using automated remediations. -* **in_entity**: What are we evaluating? This defines the entity that’s being evaluated. It could be repository, artifact, pull_request, and build_environment (coming soon). -* **param_schema**: Optional fields to pass to the ingestion (more on this later). This is handy if we need extra data to get the observed state of an entity. -* **rule_schema**: Optional fields to pass to the evaluation (more on this later). This is handy for customizing how a rule is evaluated. -* **Ingest**: This step defines how we get the observed state for an entity. It could be a simple REST call, a cloning of a git repo, or even a custom action if it’s a complex rule. -* **Eval**: This is the evaluation stage, which defines the actual rule evaluation. -* **Remediation**: How do we fix the issue? This defines the action to be taken when we need to fix an issue. This is what happens when you enable automated remediations. -* **Alert**: How do we notify folks about the issue? This may take the form of a GitHub Security Advisory, but we’ll support more alerting systems in the near future. +- **Description**: What does the rule do? This is handy to browse through rule + types when building a profile. +- **Guidance**: What do I do if this rule presents a “failure”? This is handy to + inform folks of what to do in case they’re not using automated remediations. +- **in_entity**: What are we evaluating? This defines the entity that’s being + evaluated. It could be repository, artifact, pull_request, and + build_environment (coming soon). +- **param_schema**: Optional fields to pass to the ingestion (more on this + later). This is handy if we need extra data to get the observed state of an + entity. +- **rule_schema**: Optional fields to pass to the evaluation (more on this + later). This is handy for customizing how a rule is evaluated. +- **Ingest**: This step defines how we get the observed state for an entity. It + could be a simple REST call, a cloning of a git repo, or even a custom action + if it’s a complex rule. +- **Eval**: This is the evaluation stage, which defines the actual rule + evaluation. +- **Remediation**: How do we fix the issue? This defines the action to be taken + when we need to fix an issue. This is what happens when you enable automated + remediations. +- **Alert**: How do we notify folks about the issue? This may take the form of a + GitHub Security Advisory, but we’ll support more alerting systems in the near + future. ## Example: Automatically delete head branches -Let's write a rule type for checking that GitHub automatically deletes branches after a pull request has been merged. While this is not strictly a security setting, it is a good practice to keep your branches clean to avoid confusion. +Let's write a rule type for checking that GitHub automatically deletes branches +after a pull request has been merged. While this is not strictly a security +setting, it is a good practice to keep your branches clean to avoid confusion. ### Ingestion / Evaluation -The first thing we need to figure out is how to get the observed state of what we want to evaluate on. This is the ingestion part. +The first thing we need to figure out is how to get the observed state of what +we want to evaluate on. This is the ingestion part. -Fortunately for us, GitHub keeps up-to-date and extensive documentation on their APIs. A quick internet search leads us to the relevant [Repositories API](https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#get-a-repository) where we can see that a call to the `/repos/OWNER/REPO` endpoint gives us the following key: `delete_branch_on_merge`. +Fortunately for us, GitHub keeps up-to-date and extensive documentation on their +APIs. A quick internet search leads us to the relevant +[Repositories API](https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#get-a-repository) +where we can see that a call to the `/repos/OWNER/REPO` endpoint gives us the +following key: `delete_branch_on_merge`. So, by now we know that we may fetch this information via a simple REST call. @@ -79,11 +113,24 @@ def: parse: json ``` -While you could hard-code the user/org and name of the repository you want to evaluate, that kind of rule is not handy, especially if you want to enroll multiple repositories in Minder. Thus, Minder has a templating system that allows you to base multiple parts of the rule type on the entity you’re evaluating (remember the in_entity part of the rule type?). The fields you may use are part of the entity’s protobuf, which can be found in [our documentation](https://minder-docs.stacklok.dev/ref/proto#repository). - -Now, we want to tell Minder what to actually evaluate from that state. This is the evaluation step. In our case, we want to verify that delete_branch_on_merge is set to true. For our intent, we have a very simple evaluation driver that will do the trick just fine! That is the [jq evaluation type](https://jqlang.github.io/jq/). - -I understand this is not a setting that everybody would want, and, in fact, some folks might want that setting to be off. This is something we can achieve with a simple toggle. To do it, we need to add a rule_schema to our rule, which would allow us to have a configurable setting in our rule. +While you could hard-code the user/org and name of the repository you want to +evaluate, that kind of rule is not handy, especially if you want to enroll +multiple repositories in Minder. Thus, Minder has a templating system that +allows you to base multiple parts of the rule type on the entity you’re +evaluating (remember the in_entity part of the rule type?). The fields you may +use are part of the entity’s protobuf, which can be found in +[our documentation](https://minder-docs.stacklok.dev/ref/proto#repository). + +Now, we want to tell Minder what to actually evaluate from that state. This is +the evaluation step. In our case, we want to verify that delete_branch_on_merge +is set to true. For our intent, we have a very simple evaluation driver that +will do the trick just fine! That is the +[jq evaluation type](https://jqlang.github.io/jq/). + +I understand this is not a setting that everybody would want, and, in fact, some +folks might want that setting to be off. This is something we can achieve with a +simple toggle. To do it, we need to add a rule_schema to our rule, which would +allow us to have a configurable setting in our rule. The evaluation would look as follows: @@ -100,19 +147,20 @@ def: eval: type: jq jq: - - ingested: - def: '.delete_branch_on_merge' - profile: - def: ".enabled" + - ingested: + def: '.delete_branch_on_merge' + profile: + def: '.enabled' ``` - - -The rule type above now allows us to compare the delete_branch_on_merge setting we got from the GitHub call, and evaluate it against the enabled setting we've registered for our rule type. +The rule type above now allows us to compare the delete_branch_on_merge setting +we got from the GitHub call, and evaluate it against the enabled setting we've +registered for our rule type. ### Alerting -We'll now describe how you may get a notification if your repository doesn’t adhere to the rule. This is as simple as adding the following to the manifest: +We'll now describe how you may get a notification if your repository doesn’t +adhere to the rule. This is as simple as adding the following to the manifest: ```yaml --- @@ -120,14 +168,19 @@ def: alert: type: security_advisory security_advisory: - severity: "low" + severity: 'low' ``` -This will create a security advisory in your GitHub repository that you’ll be able to browse for information. Minder knows already what information to fill-in to make the alert relevant. +This will create a security advisory in your GitHub repository that you’ll be +able to browse for information. Minder knows already what information to fill-in +to make the alert relevant. ### Remediation -Minder has the ability to auto-fix issues that it finds in your supply chain, let’s add an automated fix to this rule! Similarly to ingestion, remediations also have several flavors or types. For our case, a simple REST remediation suffices. +Minder has the ability to auto-fix issues that it finds in your supply chain, +let’s add an automated fix to this rule! Similarly to ingestion, remediations +also have several flavors or types. For our case, a simple REST remediation +suffices. Let’s see how it would look: @@ -138,16 +191,24 @@ def: type: rest rest: method: PATCH - endpoint: "/repos/{{.Entity.Owner}}/{{.Entity.Name}}" + endpoint: '/repos/{{.Entity.Owner}}/{{.Entity.Name}}' body: | { "delete_branch_on_merge": {{ .Profile.enabled }} } ``` -This effectively would do a PATCH REST call to the GitHub API if it finds that the rule is out of compliance. We’re able to parametrize the call with whatever we defined in the profile using golang templates (that’s the `{{ .Profile.enabled }}` section you see in the message’s body). +This effectively would do a PATCH REST call to the GitHub API if it finds that +the rule is out of compliance. We’re able to parametrize the call with whatever +we defined in the profile using golang templates (that’s the +`{{ .Profile.enabled }}` section you see in the message’s body). ### Description & Guidance -There are a couple of sections that allow us to give information to rule type users about the rule and what to do with it. These are the description and guidance. The description is simply a textual representation of what the rule type should do. Guidance is the text that will show up if the rule fails. Guidance is relevant when automatic remediations are not enabled, and we want to give folks instructions on what to do to fix the issue. +There are a couple of sections that allow us to give information to rule type +users about the rule and what to do with it. These are the description and +guidance. The description is simply a textual representation of what the rule +type should do. Guidance is the text that will show up if the rule fails. +Guidance is relevant when automatic remediations are not enabled, and we want to +give folks instructions on what to do to fix the issue. For our rule, they will look as follows: @@ -171,17 +232,22 @@ guidance: | ## Trying the rule out -The whole rule can be seen in the [Rules and Profiles GitHub repository](https://github.com/mindersec/minder-rules-and-profiles). In order to try it out, we’ll use the minder CLI, which points to the Minder server hosted by your friends at Stacklok. +The whole rule can be seen in the +[Rules and Profiles GitHub repository](https://github.com/mindersec/minder-rules-and-profiles). +In order to try it out, we’ll use the minder CLI, which points to the Minder +server hosted by your friends at Stacklok. -Before continuing, make sure you use our Quickstart to install the CLI and enroll your GitHub repos. +Before continuing, make sure you use our Quickstart to install the CLI and +enroll your GitHub repos. Let’s create the rule: ```bash -$ minder ruletype create -f rules/github/automatic_branch_deletion.yaml +$ minder ruletype create -f rules/github/automatic_branch_deletion.yaml ``` -Here, you can already see how the description gets displayed. This same description will be handy when browsing rules through `minder ruletype list`. +Here, you can already see how the description gets displayed. This same +description will be handy when browsing rules through `minder ruletype list`. Let’s now try it out! We can call our rule in a profile as follows: @@ -192,8 +258,8 @@ type: profile name: degustation-profile context: provider: github -alert: "on" -remediate: "off" +alert: 'on' +remediate: 'off' repository: - type: automatic_branch_deletion def: @@ -212,8 +278,13 @@ Now, let's view the status of the profile: $ minder profile status list -n degustation-profile -d ``` -Depending on how your repository is set up, you may see a failure or a success. If you see a failure, you can enable automated remediations and see how Minder fixes the issue for you. +Depending on how your repository is set up, you may see a failure or a success. +If you see a failure, you can enable automated remediations and see how Minder +fixes the issue for you. ## Conclusion -We’ve now created a basic new rule for Minder. There are more ingestion types, rule evaluation engines, and remediation types that we can use today, and there will be more in the future! If you need support writing your own rule types, feel free to reach out to the Minder team. +We’ve now created a basic new rule for Minder. There are more ingestion types, +rule evaluation engines, and remediation types that we can use today, and there +will be more in the future! If you need support writing your own rule types, +feel free to reach out to the Minder team. diff --git a/docs/docs/how-to/manage_profiles.md b/docs/docs/how-to/manage_profiles.md index 2ed8a831c0..85be4928c7 100644 --- a/docs/docs/how-to/manage_profiles.md +++ b/docs/docs/how-to/manage_profiles.md @@ -5,9 +5,11 @@ sidebar_position: 20 # Manage profiles -In order to detect security deviations from repositories or other entities, Minder is relying on the concepts of **Profiles**. -A profile is a definition of a verification we want to do on an entity in a pipeline. -A **profile** is an instance of a profile type and applies to all repositories in a project, with the relevant settings filled in. +In order to detect security deviations from repositories or other entities, +Minder is relying on the concepts of **Profiles**. A profile is a definition of +a verification we want to do on an entity in a pipeline. A **profile** is an +instance of a profile type and applies to all repositories in a project, with +the relevant settings filled in. An example profile is the following: @@ -29,16 +31,21 @@ repository: required_approving_review_count: 2 ``` -The full example is available in the [examples directory](https://github.com/mindersec/minder-rules-and-profiles). +The full example is available in the +[examples directory](https://github.com/mindersec/minder-rules-and-profiles). -This profile is checking that secret scanning is enabled for all repositories and that the `main` branch is protected, -requiring at least two approvals from code owners before landing a pull request. +This profile is checking that secret scanning is enabled for all repositories +and that the `main` branch is protected, requiring at least two approvals from +code owners before landing a pull request. -You'll notice that this profile calls two different rules: `secret_scanning` and `branch_protection_require_pull_request_approving_review_count`. +You'll notice that this profile calls two different rules: `secret_scanning` and +`branch_protection_require_pull_request_approving_review_count`. -Rules can be instantiated from rule types, and they are the ones that are actually doing the verification. +Rules can be instantiated from rule types, and they are the ones that are +actually doing the verification. -A rule type is a definition of a verification we want to do on an entity in a pipeline. +A rule type is a definition of a verification we want to do on an entity in a +pipeline. An example rule type is the following: @@ -86,7 +93,7 @@ def: # for each repository in the organization, we use a template that # will be evaluated for each repository. The structure to use is the # protobuf structure for the entity that is being evaluated. - endpoint: "/repos/{{.Entity.Owner}}/{{.Entity.Name}}" + endpoint: '/repos/{{.Entity.Owner}}/{{.Entity.Name}}' # This is the method to use to retrieve the data. It should already default to JSON parse: json # Defines the configuration for evaluating data ingested against the given profile @@ -116,20 +123,24 @@ def: input.profile.skip_private_repos == true input.ingested.private == true } - ``` -The full example is available in the [examples directory](https://github.com/mindersec/minder-rules-and-profiles) +The full example is available in the +[examples directory](https://github.com/mindersec/minder-rules-and-profiles) This rule type is checking that secret scanning is enabled for all repositories. -The rule type defines how the upstream GitHub API is to be queried, and how the data is to be evaluated. -It also defines how instances of this rule will be validated against the rule schema. - -When a profile is created for an specific group, a continuous monitoring for the related objects start. An object can be a repository, -a branch, a package... depending on the profile definition. When an specific object is not matching what's expected, -a violation is presented via the profile's **status**. When a violation happens, the overall **Profile status** for this specific entity changes, -becoming failed. There is also individual statuses for each rule evaluation. User can check the reason for this violation and take remediation +The rule type defines how the upstream GitHub API is to be queried, and how the +data is to be evaluated. It also defines how instances of this rule will be +validated against the rule schema. + +When a profile is created for an specific group, a continuous monitoring for the +related objects start. An object can be a repository, a branch, a package... +depending on the profile definition. When an specific object is not matching +what's expected, a violation is presented via the profile's **status**. When a +violation happens, the overall **Profile status** for this specific entity +changes, becoming failed. There is also individual statuses for each rule +evaluation. User can check the reason for this violation and take remediation actions to comply with the profile. ## Prerequisites @@ -141,7 +152,8 @@ actions to comply with the profile. Covered rule types are now: -- branch_protection_require_pull_request_approving_review_count: controls the branch protection approving review count rule on a repo +- branch_protection_require_pull_request_approving_review_count: controls the + branch protection approving review count rule on a repo - secret_scanning: enforces secret scanning for a repo You can list all profile types registered in Minder: @@ -150,31 +162,35 @@ You can list all profile types registered in Minder: minder ruletype list ``` -By default, a rule type is providing some recommended default values, so users can create profiles -by using those defaults without having to create a new profile from scratch. +By default, a rule type is providing some recommended default values, so users +can create profiles by using those defaults without having to create a new +profile from scratch. ## Create a rule type -Before creating a profile, we need to ensure that all rule types exist in Minder. +Before creating a profile, we need to ensure that all rule types exist in +Minder. -A rule type can be created by pointing to a directory (or file) containing the rule type definition: +A rule type can be created by pointing to a directory (or file) containing the +rule type definition: ```bash minder ruletype create -f ./examples/rules-and-profiles/rule-types/github/secret_scanning.yaml ``` -Where the yaml files in the directory `rule-types` may look as the example above. +Where the yaml files in the directory `rule-types` may look as the example +above. -Once all the relevant rule types are available for our group, we may take them into use -by creating a profile. +Once all the relevant rule types are available for our group, we may take them +into use by creating a profile. ## Create a profile -When there is a need to control the specific behaviours for a set of repositories, a profile can be -created, based on the previous profile types. +When there is a need to control the specific behaviours for a set of +repositories, a profile can be created, based on the previous profile types. -A profile needs to be associated with a provider, created within a certain project and it will be applied -to all repositories belonging to that project. +A profile needs to be associated with a provider, created within a certain +project and it will be applied to all repositories belonging to that project. For example creating a profile happens by running: @@ -184,19 +200,21 @@ minder profile create -f ./examples/rules-and-profiles/profiles/github/profile.y Where `profile.yaml` may look as the example above. -When a specific setting is not provided, the value of this setting is not compared against the profile. -This specific profile will monitor the `main` branch for all registered repositories, checking that pull -request enforcement is on place, requiring at least 2 code owners approvals before landing. -It will also require that force pushes and deletions are disabled for the `main` branch. +When a specific setting is not provided, the value of this setting is not +compared against the profile. This specific profile will monitor the `main` +branch for all registered repositories, checking that pull request enforcement +is on place, requiring at least 2 code owners approvals before landing. It will +also require that force pushes and deletions are disabled for the `main` branch. -When a profile is created, any repos registered for the same provider and project, -are being reconciled. Each time that there is a change on the repo it causes the related profile status to be updated. +When a profile is created, any repos registered for the same provider and +project, are being reconciled. Each time that there is a change on the repo it +causes the related profile status to be updated. ## List profile status -When there is an event that causes a profile violation, the violation is stored in the database, and the -overall status of the profile for this specific repository is changed. -The `profile status` command will inform about: +When there is an event that causes a profile violation, the violation is stored +in the database, and the overall status of the profile for this specific +repository is changed. The `profile status` command will inform about: - profile_type (secret_scanning...) - status: [success, failure] diff --git a/docs/docs/how-to/mindev.md b/docs/docs/how-to/mindev.md index fbad6fc788..64f7226bab 100644 --- a/docs/docs/how-to/mindev.md +++ b/docs/docs/how-to/mindev.md @@ -4,9 +4,12 @@ sidebar_position: 120 # Using Mindev to develop and debug rule types -[Mindev](https://github.com/mindersec/minder/tree/main/cmd/dev) is a tool that helps you develop and debug rule types for Minder. It provides a way to run rule types locally and test them against your codebase. +[Mindev](https://github.com/mindersec/minder/tree/main/cmd/dev) is a tool that +helps you develop and debug rule types for Minder. It provides a way to run rule +types locally and test them against your codebase. -While it contains more utilities, this guide focuses on using Mindev to develop and debug rule types. +While it contains more utilities, this guide focuses on using Mindev to develop +and debug rule types. ## Prerequisites @@ -33,9 +36,9 @@ mindev ruletype help ## Linting -`ruletype lint` will evaluate the rule, without running it against any -external resources. This will allow you to identify syntax errors -quickly. To lint your rule type, run: +`ruletype lint` will evaluate the rule, without running it against any external +resources. This will allow you to identify syntax errors quickly. To lint your +rule type, run: ```bash mindev ruletype lint -r path/to/rule-type.yaml @@ -45,15 +48,15 @@ This will give you basic validations on the rule type file. ## Running a rule type -`ruletype test` will execute a rule against an external resource. This -will allow you to test a single rule. You must provide a rule type to -evaluate, the profile to evaluate it in the context of, and the information -about the entity to evaluate. +`ruletype test` will execute a rule against an external resource. This will +allow you to test a single rule. You must provide a rule type to evaluate, the +profile to evaluate it in the context of, and the information about the entity +to evaluate. -The entity type must match the rule's `def.in_entity` type; the entity -is defined as a set of YAML properties in the entity file; for example, -if you're testing a rule type that's targetted towards a repository, -the YAML must match the repository schema. +The entity type must match the rule's `def.in_entity` type; the entity is +defined as a set of YAML properties in the entity file; for example, if you're +testing a rule type that's targetted towards a repository, the YAML must match +the repository schema. To run a rule type, use the following command: @@ -67,18 +70,22 @@ Where the flags are: - `-p` or `--profile`: The path to the profile file - `-r` or `--rule`: The path to the rule file -The entity could be the repository or the codebase you want to test the rule type against. +The entity could be the repository or the codebase you want to test the rule +type against. The rule is the rule type definition you want to verify -And the profile is needed so we can specify the parameters and definitions for the rule type. +And the profile is needed so we can specify the parameters and definitions for +the rule type. ## Entity -An entity in minder is the target in the supply chain that minder is evaluating. In some cases, it may -be the repository. Minder the minimal information needed to evaluate the rule type. +An entity in minder is the target in the supply chain that minder is evaluating. +In some cases, it may be the repository. Minder the minimal information needed +to evaluate the rule type. -The values needed must match an entity's protobuf definition. for instance, for a repository entity, the following fields are required: +The values needed must match an entity's protobuf definition. for instance, for +a repository entity, the following fields are required: ```yaml --- @@ -91,21 +98,24 @@ is_private: is_fork: ``` -Minder is able to use these values to check the current state of the repository and evaluate the rule type. +Minder is able to use these values to check the current state of the repository +and evaluate the rule type. You can see examples of the schema for each entity in the -[entity examples](https://github.com/mindersec/minder/tree/main/cmd/dev/examples) folder. +[entity examples](https://github.com/mindersec/minder/tree/main/cmd/dev/examples) +folder. ## Authentication -If the rule type requires authentication, you can use the following environment variable: +If the rule type requires authentication, you can use the following environment +variable: ```bash export TEST_AUTH_TOKEN=your_token ``` -You can use [`gh` (the GitHub CLI)](https://github.com/cli/cli) to -produce a GitHub auth token. For example: +You can use [`gh` (the GitHub CLI)](https://github.com/cli/cli) to produce a +GitHub auth token. For example: ```bash TEST_AUTH_TOKEN=$(gh auth token) mindev ruletype test -e /path/to/entity -p /path/to/profile -r /path/to/rule @@ -113,9 +123,11 @@ TEST_AUTH_TOKEN=$(gh auth token) mindev ruletype test -e /path/to/entity -p /pat ### Example -Let's evaluate if the `minder` repository has set up dependabot for golang dependencies correctly. +Let's evaluate if the `minder` repository has set up dependabot for golang +dependencies correctly. -We can get the necessary rule type from the [minder rules and profiles repo](https://github.com/mindersec/minder-rules-and-profiles). +We can get the necessary rule type from the +[minder rules and profiles repo](https://github.com/mindersec/minder-rules-and-profiles). We'll create a file called `entity.yaml` with the following content: @@ -141,8 +153,8 @@ name: dependabot-go-github-profile display_name: Dependabot for Go projects context: provider: github -alert: "on" -remediate: "off" +alert: 'on' +remediate: 'off' repository: - type: dependabot_configured def: @@ -151,7 +163,8 @@ repository: apply_if_file: go.mod ``` -This is already available in the [minder rules and profiles repo](https://github.com/mindersec/minder-rules-and-profiles/blob/main/profiles/github/dependabot_go.yaml). +This is already available in the +[minder rules and profiles repo](https://github.com/mindersec/minder-rules-and-profiles/blob/main/profiles/github/dependabot_go.yaml). Let's set up authentication: @@ -167,15 +180,21 @@ Profile valid according to the JSON schema! The rule type is valid and the entity conforms to it ``` -The output shows that the rule type is valid and the entity conforms to it. Meaning the `minder` repository has set up dependabot for golang dependencies correctly. +The output shows that the rule type is valid and the entity conforms to it. +Meaning the `minder` repository has set up dependabot for golang dependencies +correctly. ## Rego print -Mindev also has the necessary pieces set up so you can debug your rego rules. e.g. `print` statements -in rego will be printed to the console. +Mindev also has the necessary pieces set up so you can debug your rego rules. +e.g. `print` statements in rego will be printed to the console. -For more information on the rego print statement, the following blog post is a good resource: [Introducing the OPA print function](https://blog.openpolicyagent.org/introducing-the-opa-print-function-809da6a13aee) +For more information on the rego print statement, the following blog post is a +good resource: +[Introducing the OPA print function](https://blog.openpolicyagent.org/introducing-the-opa-print-function-809da6a13aee) ## Conclusion -Mindev is a powerful tool that helps you develop and debug rule types for Minder. It provides a way to run rule types locally and test them against your codebase. +Mindev is a powerful tool that helps you develop and debug rule types for +Minder. It provides a way to run rule types locally and test them against your +codebase. diff --git a/docs/docs/how-to/pr_reviews.md b/docs/docs/how-to/pr_reviews.md index 48bb2b9e1f..309cecfbef 100644 --- a/docs/docs/how-to/pr_reviews.md +++ b/docs/docs/how-to/pr_reviews.md @@ -2,8 +2,8 @@ title: Enabling pull request reviews sidebar_position: 50 --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; + +import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; ## Prerequisites @@ -13,41 +13,47 @@ import TabItem from '@theme/TabItem'; - An enrolled Provider (e.g., GitHub) and registered repositories ## Create the PR vulnerability check rule -Start by creating a rule that checks if a pull request adds a new dependency with known vulnerabilities. If it does, -Minder will review the PR and suggest changes. + +Start by creating a rule that checks if a pull request adds a new dependency +with known vulnerabilities. If it does, Minder will review the PR and suggest +changes. Note that Minder is only able to review a PR if it's running under a different user than the one that created the PR. If the PR is created by the same user, -Minder only provides a comment with the vulnerability information. An alternative -is to use the `commit-status` action instead of `review` where Minder will set -the commit status to `failure` if the PR introduces a new vulnerability which can -then be used to block the PR. This requires an additional step though, where -the repo needs to require the `minder.stacklok.dev/pr-vulncheck` status to -be passing. +Minder only provides a comment with the vulnerability information. An +alternative is to use the `commit-status` action instead of `review` where +Minder will set the commit status to `failure` if the PR introduces a new +vulnerability which can then be used to block the PR. This requires an +additional step though, where the repo needs to require the +`minder.stacklok.dev/pr-vulncheck` status to be passing. This is a reference rule provider by the Minder team. -Fetch all the reference rules by cloning the [minder-rules-and-profiles repository](https://github.com/mindersec/minder-rules-and-profiles). +Fetch all the reference rules by cloning the +[minder-rules-and-profiles repository](https://github.com/mindersec/minder-rules-and-profiles). ``` git clone https://github.com/mindersec/minder-rules-and-profiles.git ``` In that directory you can find all the reference rules and profiles. + ``` cd minder-rules-and-profiles ``` Create the `pr_vulnerability_check` rule type in Minder: + ``` minder ruletype create -f rule-types/github/pr_vulnerability_check.yaml ``` ## Create a profile + Next, create a profile that applies the rule to all registered repositories. -Create a new file called `profile.yaml`. -Based on your source code language, paste the following profile definition into the newly created file. +Create a new file called `profile.yaml`. Based on your source code language, +paste the following profile definition into the newly created file. @@ -59,8 +65,8 @@ type: profile name: pr-review-profile context: provider: github -alert: "on" -remediate: "off" +alert: 'on' +remediate: 'off' pull_request: - type: pr_vulnerability_check def: @@ -85,8 +91,8 @@ type: profile name: pr-review-profile context: provider: github -alert: "on" -remediate: "off" +alert: 'on' +remediate: 'off' pull_request: - type: pr_vulnerability_check def: @@ -109,8 +115,8 @@ type: profile name: pr-review-profile context: provider: github -alert: "on" -remediate: "off" +alert: 'on' +remediate: 'off' pull_request: - type: pr_vulnerability_check def: @@ -127,14 +133,17 @@ pull_request: Create the profile in Minder: + ``` minder profile create -f profile.yaml ``` -Once the profile is created, Minder will monitor any pull requests to the registered repositories. If a pull -request brings in a dependency with a known vulnerability, then Minder will add a review to the pull request and -suggest changes. +Once the profile is created, Minder will monitor any pull requests to the +registered repositories. If a pull request brings in a dependency with a known +vulnerability, then Minder will add a review to the pull request and suggest +changes. -Alerts are complementary to the remediation feature. If you have both `alert` and `remediation` enabled for a profile, -Minder will attempt to remediate it first. If the remediation fails, Minder will create an alert. If the remediation +Alerts are complementary to the remediation feature. If you have both `alert` +and `remediation` enabled for a profile, Minder will attempt to remediate it +first. If the remediation fails, Minder will create an alert. If the remediation succeeds, Minder will close any previously opened alerts related to that rule. diff --git a/docs/docs/how-to/profile_selectors.md b/docs/docs/how-to/profile_selectors.md index b1e1d9521d..ad7154e02a 100644 --- a/docs/docs/how-to/profile_selectors.md +++ b/docs/docs/how-to/profile_selectors.md @@ -5,10 +5,12 @@ title: Apply a profile to a subset of entities # Apply a profile to a subset of entities -Profiles allow you to apply a consistent set of rules to a group of entities within your project. By default, these -profiles are applied universally across all entities in a project. However, you may need to target a specific subset, such as -repositories belonging to a specific organization. Minder simplifies this process with profile selectors, enabling you -to easily customize which entities a profile applies to. +Profiles allow you to apply a consistent set of rules to a group of entities +within your project. By default, these profiles are applied universally across +all entities in a project. However, you may need to target a specific subset, +such as repositories belonging to a specific organization. Minder simplifies +this process with profile selectors, enabling you to easily customize which +entities a profile applies to. ## Prerequisites @@ -19,93 +21,111 @@ to easily customize which entities a profile applies to. ## Add a selector to a profile -Selectors are written using [CEL (Common Expression Language)](https://github.com/google/cel-spec). To add a selector to -your profile, you need to define the entity and the condition you want to apply. Below is an example showing how to -configure a selector to filter repositories and artifacts: +Selectors are written using +[CEL (Common Expression Language)](https://github.com/google/cel-spec). To add a +selector to your profile, you need to define the entity and the condition you +want to apply. Below is an example showing how to configure a selector to filter +repositories and artifacts: ```yaml name: profile-with-selectors selection: - entity: repository - selector: repository.is_fork != true && repository.name.startsWith('stacklok/') + selector: + repository.is_fork != true && repository.name.startsWith('stacklok/') - entity: artifact selector: artifact.provider.name == 'github-app-stacklok' - entity: repository selector: repository.properties['github/license'].contains('GPL') == true - comment: "Be extra careful with GPL licenses" + comment: 'Be extra careful with GPL licenses' - entity: repository selector: repository.properties['github/primary_language'] == 'Go' - comment: "Only Go repositories" + comment: 'Only Go repositories' - entity: repository selector: repository.provider.class.contains('github') - comment: "Only github repositories" + comment: 'Only github repositories' ``` Let's break down the example above: -- `entity`: Defines the type of entity you want to filter (`repository`, `artifact`, or `pull_request`). In the case that the `entity` type is omitted, the selector will be applied to all entities. -- `selector`: The CEL expression that specifies the filtering criteria. In the example: - - The first selector filters repositories to include only those that are not forks and whose name starts with stacklok. In other words, those that are part of the stacklok organization. - - The second selector filters artifacts to include only those provided by `github-app-stacklok`. - - The third selector filters repositories to include only those with a GPL license and the fourth selector filters repositories to include only those written in Go. These two selectors use the properties map which is provider-specific. - - The fourth selector filters repositories to include only that use Go as the primary language. - - The fifth selector filters repositories to include only those provided by the GitHub provider. We use the `contains` function to check if the provider class contains the string `github` to cover for both `github` and `github-app` providers. +- `entity`: Defines the type of entity you want to filter (`repository`, + `artifact`, or `pull_request`). In the case that the `entity` type is omitted, + the selector will be applied to all entities. +- `selector`: The CEL expression that specifies the filtering criteria. In the + example: + - The first selector filters repositories to include only those that are not + forks and whose name starts with stacklok. In other words, those that are + part of the stacklok organization. + - The second selector filters artifacts to include only those provided by + `github-app-stacklok`. + - The third selector filters repositories to include only those with a GPL + license and the fourth selector filters repositories to include only those + written in Go. These two selectors use the properties map which is + provider-specific. + - The fourth selector filters repositories to include only that use Go as the + primary language. + - The fifth selector filters repositories to include only those provided by + the GitHub provider. We use the `contains` function to check if the provider + class contains the string `github` to cover for both `github` and + `github-app` providers. Below you can find the full list of selectors available for each entity type. ## Repository selectors -Selectors for repositories allow you to filter and manage repositories based on specific attributes and properties. The attributes are common to all providers, while the properties are provider-specific and prefixed with the provider name. +Selectors for repositories allow you to filter and manage repositories based on +specific attributes and properties. The attributes are common to all providers, +while the properties are provider-specific and prefixed with the provider name. | Field | Description | Type | -|--------------|-------------------------------------------------------------------------------------------------------|------------------| -| `name` | The full name of the repository, e.g. mindersec/minder | string | +| ------------ | ----------------------------------------------------------------------------------------------------- | ---------------- | +| `name` | The full name of the repository, e.g. mindersec/minder | string | | `is_fork` | `true` if the repository is a fork, `nil` if unknown or not applicable to this provider | bool | | `is_private` | `true` if the repository is private, `nil` if unknown or not applicable to this provider | bool | | `provider` | The provider of the repository, for more details see [Provider Selectors](#entity-provider-selectors) | ProviderSelector | ## Repository properties set by the GitHub provider -| Field | Description | Type | -|-----------------------------|-----------------------------------------------------------------------|----------| -| `github/license` | The license of the repository, e.g. MIT, GPL, Apache-2.0, etc. | string | -| `github/primary_language` | The primary language of the repository, e.g. Go, Python, Java, etc. | string | -| `github/default_branch` | The default branch of the repository, e.g. `main`, `master`, etc. | string | -| `github/repo_id` | The github repo ID | integer | -| `github/repo_name` | The github repo name (e.g. `stacklok`) | string | -| `github/repo_owner` | The github repo owner (e.g. `minder`) | string | +| Field | Description | Type | +| ------------------------- | ------------------------------------------------------------------- | ------- | +| `github/license` | The license of the repository, e.g. MIT, GPL, Apache-2.0, etc. | string | +| `github/primary_language` | The primary language of the repository, e.g. Go, Python, Java, etc. | string | +| `github/default_branch` | The default branch of the repository, e.g. `main`, `master`, etc. | string | +| `github/repo_id` | The github repo ID | integer | +| `github/repo_name` | The github repo name (e.g. `stacklok`) | string | +| `github/repo_owner` | The github repo owner (e.g. `minder`) | string | ## Artifact selectors | Field | Description | Type | -|------------|-----------------------------------------------------------------------------------------------------|------------------| -| `name` | The full name of the artifact, e.g. mindersec/minder-server | string | +| ---------- | --------------------------------------------------------------------------------------------------- | ---------------- | +| `name` | The full name of the artifact, e.g. mindersec/minder-server | string | | `type` | The type of the artifact, e.g. "container" | string | | `provider` | The provider of the artifact, for more details see [Provider Selectors](#entity-provider-selectors) | ProviderSelector | ## Artifact properties set by the GitHub provider -| Field | Description | Type | -|---------------------|-----------------------------------------------------------------------------|--------| -| `github/created_at` | The time the artifact was created formatted as RFC3339 string | string | -| `github/name` | The full name of the artifact. | string | -| `github/type` | The type of the artifact, e.g. "container" | string | -| `github/visibility` | The visibility of the artifact, e.g. "public" | string | -| `github/owner` | The full name of the artifact owner. Can be a repo or an org. | string | +| Field | Description | Type | +| ------------------- | ---------------------------------------------------------------------------- | ------ | +| `github/created_at` | The time the artifact was created formatted as RFC3339 string | string | +| `github/name` | The full name of the artifact. | string | +| `github/type` | The type of the artifact, e.g. "container" | string | +| `github/visibility` | The visibility of the artifact, e.g. "public" | string | +| `github/owner` | The full name of the artifact owner. Can be a repo or an org. | string | | `github/repo` | The github repo full name (e.g. `mindersec/minder`). Empty for org packages. | string | -| `github/repo_name` | The github repo name (e.g. `stacklok`). Empty for org packages. | string | -| `github/repo_owner` | The github repo owner (e.g. `minder`). Empty for org packages. | string | +| `github/repo_name` | The github repo name (e.g. `stacklok`). Empty for org packages. | string | +| `github/repo_owner` | The github repo owner (e.g. `minder`). Empty for org packages. | string | ## Pull request selectors -| Field | Description | Type | -|--------|-------------------------------------------------------------|--------| +| Field | Description | Type | +| ------ | ------------------------------------------------------------ | ------ | | `name` | The full name of the pull request, e.g. mindersec/minder/123 | string | ## Pull request properties set by the GitHub provider | Field | Description | Type | -|----------------------------|----------------------------------------------------|--------| +| -------------------------- | -------------------------------------------------- | ------ | | `github/pull_url` | The URL of the pull request | string | | `github/pull_number` | The number of the pull request | string | | `github/pull_author_id` | The numerical ID of the author of the pull request | int | @@ -118,6 +138,6 @@ Selectors for repositories allow you to filter and manage repositories based on Each entity can be filtered based on its provider. | Field | Description | Type | -|---------|----------------------------------------------------|--------| +| ------- | -------------------------------------------------- | ------ | | `name` | The name of the provider, e.g. github-app-stacklok | string | | `class` | The class of the provider, e.g. github-app | string | diff --git a/docs/docs/how-to/remediate-pullrequest.md b/docs/docs/how-to/remediate-pullrequest.md index 9d3a426074..4770847194 100644 --- a/docs/docs/how-to/remediate-pullrequest.md +++ b/docs/docs/how-to/remediate-pullrequest.md @@ -3,8 +3,7 @@ title: Automatic remediation via Pull Request sidebar_position: 65 --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; +import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; # Creating a pull request for automatic remediation @@ -17,25 +16,29 @@ import TabItem from '@theme/TabItem'; ## Create a rule type that has support for pull request automatic remediation -The pull request automatic remediation feature provides the functionality to fix a failed rule type by creating a pull request. +The pull request automatic remediation feature provides the functionality to fix +a failed rule type by creating a pull request. -This feature is only available for rule types that support it. To find out if a rule type supports it, check the -`remediate` section in their `.yaml` file. It should have the `pull_request` section defined like below: +This feature is only available for rule types that support it. To find out if a +rule type supports it, check the `remediate` section in their +`.yaml` file. It should have the `pull_request` section defined like +below: ```yaml version: v1 type: rule-type -... - remediate: - type: pull_request -... +--- +remediate: + type: pull_request ``` -In this example, we will use a rule type that checks if a repository has Dependabot enabled. If it's not enabled, Minder -will create a pull request that enables Dependabot. The rule type is called `dependabot_configured.yaml` and is +In this example, we will use a rule type that checks if a repository has +Dependabot enabled. If it's not enabled, Minder will create a pull request that +enables Dependabot. The rule type is called `dependabot_configured.yaml` and is one of the reference rule types provided by the Minder team. -Fetch all the reference rules by cloning the [minder-rules-and-profiles repository](https://github.com/mindersec/minder-rules-and-profiles). +Fetch all the reference rules by cloning the +[minder-rules-and-profiles repository](https://github.com/mindersec/minder-rules-and-profiles). ```bash git clone https://github.com/mindersec/minder-rules-and-profiles.git @@ -54,11 +57,13 @@ minder ruletype create -f rule-types/github/dependabot_configured.yaml ``` ## Create a profile + Next, create a profile that applies the rule to all registered repositories. Create a new file called `profile.yaml`. -Based on your source code language, paste the following profile definition into the newly created file. +Based on your source code language, paste the following profile definition into +the newly created file. @@ -70,8 +75,8 @@ type: profile name: dependabot-profile context: provider: github -alert: "on" -remediate: "on" +alert: 'on' +remediate: 'on' repository: - type: dependabot_configured def: @@ -90,8 +95,8 @@ type: profile name: dependabot-profile context: provider: github -alert: "on" -remediate: "on" +alert: 'on' +remediate: 'on' repository: - type: dependabot_configured def: @@ -99,6 +104,7 @@ repository: schedule_interval: weekly apply_if_file: package.json ``` + @@ -108,19 +114,25 @@ Create the profile in Minder: minder profile create -f profile.yaml ``` -Once the profile is created, Minder will monitor all of your registered repositories matching the expected ecosystem, -i.e., Go, NPM, etc. +Once the profile is created, Minder will monitor all of your registered +repositories matching the expected ecosystem, i.e., Go, NPM, etc. -If a repository does not have Dependabot enabled, Minder will create a pull request with the necessary configuration -to enable it. Alongside the pull request, Minder will also create a Security Advisory alert that will be present until the issue -is resolved. +If a repository does not have Dependabot enabled, Minder will create a pull +request with the necessary configuration to enable it. Alongside the pull +request, Minder will also create a Security Advisory alert that will be present +until the issue is resolved. -Alerts are complementary to the remediation feature. If you have both `alert` and `remediation` enabled for a profile, -Minder will attempt to remediate it first. If the remediation fails, Minder will create an alert. If the remediation +Alerts are complementary to the remediation feature. If you have both `alert` +and `remediation` enabled for a profile, Minder will attempt to remediate it +first. If the remediation fails, Minder will create an alert. If the remediation succeeds, Minder will close any previously opened alerts related to that rule. ## Limitations -* The pull request automatic remediation feature is only available for rule types that support it. -* There's no support for creating pull requests that modify the content of existing files yet. -* The created pull request should be closed manually if the issue is resolved through other means. The profile status and any related alerts will be updated/closed automatically. +- The pull request automatic remediation feature is only available for rule + types that support it. +- There's no support for creating pull requests that modify the content of + existing files yet. +- The created pull request should be closed manually if the issue is resolved + through other means. The profile status and any related alerts will be + updated/closed automatically. diff --git a/docs/docs/how-to/setup-alerts.md b/docs/docs/how-to/setup-alerts.md index 4c2f4b54a2..6267977a3f 100644 --- a/docs/docs/how-to/setup-alerts.md +++ b/docs/docs/how-to/setup-alerts.md @@ -14,20 +14,26 @@ sidebar_position: 70 ## Create a rule type that you want to be alerted on -The `alert` feature is available for all rule types that have the `alert` section defined in their `.yaml` -file. Alerts are a core feature of Minder providing you with notifications about the status of your registered -repositories using GitHub Security Advisories. These Security Advisories automatically open and close based on the evaluation of the rules -defined in your profiles. - -When a rule fails, Minder opens an alert to bring your attention to the non-compliance issue. Conversely, when the -rule evaluation passes, Minder will automatically close any previously opened alerts related to that rule. - -In this example, we will use a rule type that checks if a repository has a LICENSE file present. If there's no file -present, Minder will create an alert notifying the owner of the repository. The rule type is called `license.yaml` and -is one of the reference rule types provided by the Minder team. Details, such as the severity of the alert are defined -in the `alert` section of the rule type definition. - -Fetch all the reference rules by cloning the [minder-rules-and-profiles repository](https://github.com/mindersec/minder-rules-and-profiles). +The `alert` feature is available for all rule types that have the `alert` +section defined in their `.yaml` file. Alerts are a core feature of +Minder providing you with notifications about the status of your registered +repositories using GitHub Security Advisories. These Security Advisories +automatically open and close based on the evaluation of the rules defined in +your profiles. + +When a rule fails, Minder opens an alert to bring your attention to the +non-compliance issue. Conversely, when the rule evaluation passes, Minder will +automatically close any previously opened alerts related to that rule. + +In this example, we will use a rule type that checks if a repository has a +LICENSE file present. If there's no file present, Minder will create an alert +notifying the owner of the repository. The rule type is called `license.yaml` +and is one of the reference rule types provided by the Minder team. Details, +such as the severity of the alert are defined in the `alert` section of the rule +type definition. + +Fetch all the reference rules by cloning the +[minder-rules-and-profiles repository](https://github.com/mindersec/minder-rules-and-profiles). ```bash git clone https://github.com/mindersec/minder-rules-and-profiles.git @@ -46,10 +52,12 @@ minder ruletype create -f rule-types/github/license.yaml ``` ## Create a profile + Next, create a profile that applies the rule to all registered repositories. -Create a new file called `profile.yaml` using the following profile definition and enable alerting by setting `alert` -to `on` (default). The other available values are `off` and `dry_run`. +Create a new file called `profile.yaml` using the following profile definition +and enable alerting by setting `alert` to `on` (default). The other available +values are `off` and `dry_run`. ```yaml --- @@ -58,12 +66,12 @@ type: profile name: license-profile context: provider: github -alert: "on" +alert: 'on' repository: - type: license def: license_filename: LICENSE - license_type: "" + license_type: '' ``` Create the profile in Minder: @@ -72,19 +80,24 @@ Create the profile in Minder: minder profile create -f profile.yaml ``` -Once the profile is created, Minder will monitor all of your registered repositories for the presence of the `LICENSE` -file. +Once the profile is created, Minder will monitor all of your registered +repositories for the presence of the `LICENSE` file. -If a repository does not have a `LICENSE` file available, Minder will create an alert of type Security Advisory providing -additional details such as the profile and rule that triggered the alert and guidelines on how to resolve the issue. +If a repository does not have a `LICENSE` file available, Minder will create an +alert of type Security Advisory providing additional details such as the profile +and rule that triggered the alert and guidelines on how to resolve the issue. -Once a `LICENSE` file is added to the repository, Minder will automatically close the alert. +Once a `LICENSE` file is added to the repository, Minder will automatically +close the alert. -Alerts are complementary to the remediation feature. If you have both `alert` and `remediation` enabled for a profile, -Minder will attempt to remediate it first. If the remediation fails, Minder will create an alert. If the remediation +Alerts are complementary to the remediation feature. If you have both `alert` +and `remediation` enabled for a profile, Minder will attempt to remediate it +first. If the remediation fails, Minder will create an alert. If the remediation succeeds, Minder will close any previously opened alerts related to that rule. ## Limitations -* Currently, the only supported alert type is GitHub Security Advisory. More alert types will be added in the future. -* Alerts are only available for rules that have the `alert` section defined in their `.yaml` file. +- Currently, the only supported alert type is GitHub Security Advisory. More + alert types will be added in the future. +- Alerts are only available for rules that have the `alert` section defined in + their `.yaml` file. diff --git a/docs/docs/how-to/setup-autoremediation.md b/docs/docs/how-to/setup-autoremediation.md index 35cc8fb976..5f42aae7b8 100644 --- a/docs/docs/how-to/setup-autoremediation.md +++ b/docs/docs/how-to/setup-autoremediation.md @@ -14,19 +14,23 @@ sidebar_position: 60 ## Create a rule type that you want to use auto-remediation on -The `remediate` feature is available for all rule types that have the `remediate` section defined in their -`.yaml` file. When the `remediate` feature is turned `on`, Minder will try to automatically remediate failed -rules based on their type, i.e., by processing a REST call to enable/disable a non-compliant repository setting or by -creating a pull request with a proposed fix. - -In this example, we will use a rule type that checks if a repository allows having force pushes on their main branch, -which is considered a security risk. If their setting allows for force pushes, Minder will automatically remediate it +The `remediate` feature is available for all rule types that have the +`remediate` section defined in their `.yaml` file. When the +`remediate` feature is turned `on`, Minder will try to automatically remediate +failed rules based on their type, i.e., by processing a REST call to +enable/disable a non-compliant repository setting or by creating a pull request +with a proposed fix. + +In this example, we will use a rule type that checks if a repository allows +having force pushes on their main branch, which is considered a security risk. +If their setting allows for force pushes, Minder will automatically remediate it and disable it. -The rule type is called `branch_protection_allow_force_pushes.yaml` and is one of the reference rule types provided by -the Minder team. +The rule type is called `branch_protection_allow_force_pushes.yaml` and is one +of the reference rule types provided by the Minder team. -Fetch all the reference rules by cloning the [minder-rules-and-profiles repository](https://github.com/mindersec/minder-rules-and-profiles). +Fetch all the reference rules by cloning the +[minder-rules-and-profiles repository](https://github.com/mindersec/minder-rules-and-profiles). ```bash git clone https://github.com/mindersec/minder-rules-and-profiles.git @@ -48,8 +52,9 @@ minder ruletype create -f rule-types/github/branch_protection_allow_force_pushes Next, create a profile that applies the rule to all registered repositories. -Create a new file called `profile.yaml` using the following profile definition and enable automatic remediation by setting -`remediate` to `on`. The other available values are `off`(default) and `dry_run`. +Create a new file called `profile.yaml` using the following profile definition +and enable automatic remediation by setting `remediate` to `on`. The other +available values are `off`(default) and `dry_run`. ```yaml --- @@ -58,7 +63,7 @@ type: profile name: disable-force-push-profile context: provider: github -remediate: "on" +remediate: 'on' repository: - type: branch_protection_allow_force_pushes params: @@ -73,14 +78,18 @@ Create the profile in Minder: minder profile create -f profile.yaml ``` -Once the profile is created, Minder will monitor if the `allow_force_pushes` setting on all of your registered -repositories is set to `false`. If the setting is set to `true`, Minder will automatically remediate it by disabling it -and will make sure to keep it that way until the profile is deleted. +Once the profile is created, Minder will monitor if the `allow_force_pushes` +setting on all of your registered repositories is set to `false`. If the setting +is set to `true`, Minder will automatically remediate it by disabling it and +will make sure to keep it that way until the profile is deleted. -Alerts are complementary to the remediation feature. If you have both `alert` and `remediation` enabled for a profile, -Minder will attempt to remediate it first. If the remediation fails, Minder will create an alert. If the remediation +Alerts are complementary to the remediation feature. If you have both `alert` +and `remediation` enabled for a profile, Minder will attempt to remediate it +first. If the remediation fails, Minder will create an alert. If the remediation succeeds, Minder will close any previously opened alerts related to that rule. ## Limitations -* The automatic remediation feature is only available for rule types that support it, i.e., have the `remediate` section defined in their `.yaml` file. +- The automatic remediation feature is only available for rule types that + support it, i.e., have the `remediate` section defined in their + `.yaml` file. diff --git a/docs/docs/how-to/writing-rules-in-rego.md b/docs/docs/how-to/writing-rules-in-rego.md index 1eef183758..5dd9290ac4 100644 --- a/docs/docs/how-to/writing-rules-in-rego.md +++ b/docs/docs/how-to/writing-rules-in-rego.md @@ -2,61 +2,104 @@ sidebar_position: 110 --- -# Writing rules using Rego +# Writing rules using Rego -Minder's policy engine is able to use pluggable drivers for evaluating rules. Rego is a language specifically designed for expressing policies in a clear and concise manner. Its declarative syntax makes it an excellent choice for defining policy logic. In the context of Minder, Rego plays a central role in crafting Rule Types, which are used to enforce security policies. +Minder's policy engine is able to use pluggable drivers for evaluating rules. +Rego is a language specifically designed for expressing policies in a clear and +concise manner. Its declarative syntax makes it an excellent choice for defining +policy logic. In the context of Minder, Rego plays a central role in crafting +Rule Types, which are used to enforce security policies. # Writing Rule Types in Minder -Minder organizes policies into Rule Types, each with specific sections defining how policies are ingested, evaluated, and acted upon. Rule types are then called within profiles to express the security posture of your organization. Let's delve into the essential components of a Minder Rule Type: +Minder organizes policies into Rule Types, each with specific sections defining +how policies are ingested, evaluated, and acted upon. Rule types are then called +within profiles to express the security posture of your organization. Let's +delve into the essential components of a Minder Rule Type: -* Ingesting Data: Fetching relevant data, often from external sources like GitHub API. +- Ingesting Data: Fetching relevant data, often from external sources like + GitHub API. -* Evaluation: Applying policy logic to the ingested data. Minder offers a set of engines to evaluate data: jq and rego being general-purpose engines, while Stacklok Insight and vulncheck are more use case-specific ones. +- Evaluation: Applying policy logic to the ingested data. Minder offers a set of + engines to evaluate data: jq and rego being general-purpose engines, while + Stacklok Insight and vulncheck are more use case-specific ones. -* Remediation and Alerting: Taking actions or providing notifications based on evaluation results. E.g. creating a pull request or generating a GitHub security advisory. +- Remediation and Alerting: Taking actions or providing notifications based on + evaluation results. E.g. creating a pull request or generating a GitHub + security advisory. ## Rego Evaluation types -With Rego being a flexible policy language, it allowed us to express policy checks via different constructs. We chose to implement two in Minder: +With Rego being a flexible policy language, it allowed us to express policy +checks via different constructs. We chose to implement two in Minder: -* **deny-by-default**: Checks for an allowed boolean being set to true, and denies the policy if it’s not the case. +- **deny-by-default**: Checks for an allowed boolean being set to true, and + denies the policy if it’s not the case. -* **constraints**: Checks for violations in the given policy. This allows us to express the violations and output them in a user friendly-manner. +- **constraints**: Checks for violations in the given policy. This allows us to + express the violations and output them in a user friendly-manner. -Note that these are known patterns in the OPA community, so we’re not doing anything out of the ordinary here. Instead, we leverage best practices that have already been established. +Note that these are known patterns in the OPA community, so we’re not doing +anything out of the ordinary here. Instead, we leverage best practices that have +already been established. ## Custom Rego functions -Given the context in which Minder operates, we did need to add some custom functionality that OPA doesn’t provide out of the box. Namely, we added the following custom functions: +Given the context in which Minder operates, we did need to add some custom +functionality that OPA doesn’t provide out of the box. Namely, we added the +following custom functions: -* **file.exists(filepath)**: Verifies that the given filepath exists in the Git repository, returns a boolean. +- **file.exists(filepath)**: Verifies that the given filepath exists in the Git + repository, returns a boolean. -* **file.read(filepath)**: Reads the contents of the given file in the Git repository and returns the contents as a string. +- **file.read(filepath)**: Reads the contents of the given file in the Git + repository and returns the contents as a string. -* **file.ls(directory)**: Lists files in the given directory in the Git repository, returning the filenames as an array of strings. +- **file.ls(directory)**: Lists files in the given directory in the Git + repository, returning the filenames as an array of strings. -* **file.ls_glob(pattern)**: Lists files in the given directory in the Git repository that match the given glob pattern, returning matched filenames as an array of strings. +- **file.ls_glob(pattern)**: Lists files in the given directory in the Git + repository that match the given glob pattern, returning matched filenames as + an array of strings. -* **file.http_type(filepath)**: Determines the HTTP (MIME) content type of the given file by [examining the first 512 bytes of the file](https://mimesniff.spec.whatwg.org/). It returns the content type as a string. +- **file.http_type(filepath)**: Determines the HTTP (MIME) content type of the + given file by + [examining the first 512 bytes of the file](https://mimesniff.spec.whatwg.org/). + It returns the content type as a string. -* **file.walk(path)**: Walks the given path (directory or file) in the Git repository and returns a list of paths to all regular files (not directories) as an array of strings. +- **file.walk(path)**: Walks the given path (directory or file) in the Git + repository and returns a list of paths to all regular files (not directories) + as an array of strings. -* **github_workflow.ls_actions(directory)**: Lists all actions in the given GitHub workflow directory, returning the filenames as an array of strings. +- **github_workflow.ls_actions(directory)**: Lists all actions in the given + GitHub workflow directory, returning the filenames as an array of strings. -* **parse_yaml**: Parses a YAML string into a JSON object. This implementation uses https://gopkg.in/yaml.v3, which avoids bugs when parsing `"on"` as an object _key_ (for example, in GitHub workflows). +- **parse_yaml**: Parses a YAML string into a JSON object. This implementation + uses https://gopkg.in/yaml.v3, which avoids bugs when parsing `"on"` as an + object _key_ (for example, in GitHub workflows). -* **jq.is_true(object, query)**: Evaluates a jq query against the specified object, returning `true` if the query result is a true boolean value, andh `false` otherwise. +- **jq.is_true(object, query)**: Evaluates a jq query against the specified + object, returning `true` if the query result is a true boolean value, andh + `false` otherwise. -* **file.archive(paths)**: _(experimental)_ Builds a `.tar.gz` format archive containing all files under the given paths. Returns the archive contents as a (binary) string. +- **file.archive(paths)**: _(experimental)_ Builds a `.tar.gz` format archive + containing all files under the given paths. Returns the archive contents as a + (binary) string. -_(experimental)_ In addition, when operating in a pull request context, `base_file` versions of the `file` operations are available for accessing the files in the base branch of the pull request. The `file` versions of the operations operate on the head (proposed changes) versions of the files in a pull request context. +_(experimental)_ In addition, when operating in a pull request context, +`base_file` versions of the `file` operations are available for accessing the +files in the base branch of the pull request. The `file` versions of the +operations operate on the head (proposed changes) versions of the files in a +pull request context. -In addition, most of the [standard OPA functions are available in the Minder runtime](https://www.openpolicyagent.org/docs/latest/policy-reference/#built-in-functions). +In addition, most of the +[standard OPA functions are available in the Minder runtime](https://www.openpolicyagent.org/docs/latest/policy-reference/#built-in-functions). ## Example: CodeQL-Enabled Check -CodeQL is a very handy tool that GitHub provides to do static analysis on codebases. In this scenario, we’ll see a rule type that verifies that it’s enabled via a GitHub action in the repository. +CodeQL is a very handy tool that GitHub provides to do static analysis on +codebases. In this scenario, we’ll see a rule type that verifies that it’s +enabled via a GitHub action in the repository. ```yaml --- @@ -133,14 +176,17 @@ def: alert: type: security_advisory security_advisory: - severity: "medium" + severity: 'medium' ``` -The rego evaluation uses the `deny-by-default` type. It’ll set the policy as successful if there is a GitHub workflow that instantiates `github/codeql-action/analyze`. +The rego evaluation uses the `deny-by-default` type. It’ll set the policy as +successful if there is a GitHub workflow that instantiates +`github/codeql-action/analyze`. ## Example: No 'latest' tag in Dockerfile -In this scenario, we’ll explore a Rule Type that verifies that a Dockerfile does not use the `latest` tag. +In this scenario, we’ll explore a Rule Type that verifies that a Dockerfile does +not use the `latest` tag. ```yaml --- @@ -149,7 +195,8 @@ type: rule-type name: dockerfile_no_latest_tag context: provider: github -description: Verifies that the Dockerfile image references don't use the latest tag +description: + Verifies that the Dockerfile image references don't use the latest tag guidance: | Using the latest tag for Docker images is not recommended as it can lead to unexpected behavior. It is recommended to use a checksum instead, as that's immutable and will always point to the same image. @@ -194,14 +241,17 @@ def: alert: type: security_advisory security_advisory: - severity: "medium" + severity: 'medium' ``` -This leverages the constraints Rego evaluation type, which will output a failure for each violation that it finds. This is handy for usability, as it will tell us exactly the lines that are not in conformance with our rules. +This leverages the constraints Rego evaluation type, which will output a failure +for each violation that it finds. This is handy for usability, as it will tell +us exactly the lines that are not in conformance with our rules. ## Example: Security Advisories Check -This is a more complex example. Here, we'll explore a Rule Type that checks for open security advisories in a GitHub repository. +This is a more complex example. Here, we'll explore a Rule Type that checks for +open security advisories in a GitHub repository. ```yaml --- @@ -243,7 +293,7 @@ def: ingest: type: rest rest: - endpoint: "/repos/{{.Entity.Owner}}/{{.Entity.Name}}/security-advisories?per_page=100&sort=updated&order=asc" + endpoint: '/repos/{{.Entity.Owner}}/{{.Entity.Name}}/security-advisories?per_page=100&sort=updated&order=asc' parse: json fallback: # If we don't have advisories enabled, we'll get a 404 @@ -257,11 +307,11 @@ def: violation_format: json def: | package minder - + import future.keywords.contains import future.keywords.if import future.keywords.in - + severity_to_number := { null: -1, "unknown": -1, @@ -270,48 +320,54 @@ def: "high": 2, "critical": 3, } - + default threshold := 1 - + threshold := severity_to_number[input.profile.severity] if input.profile.severity != null - + above_threshold(severity, threshold) if { severity_to_number[severity] >= threshold } - + had_fallback if { input.ingested.fallback } - + violations contains {"msg": "Security advisories not enabled."} if { had_fallback } - + violations contains {"msg": "Found open security advisories in or above threshold"} if { not had_fallback - + some adv in input.ingested - + # Is not withdrawn adv.withdrawn_at == null - + adv.state != "closed" adv.state != "published" - + # We only care about advisories that are at or above the threshold above_threshold(adv.severity, threshold) } alert: type: security_advisory security_advisory: - severity: "medium" + severity: 'medium' ``` -This verifies that a repository does not have untriaged security advisories within a given severity threshold. Thus ensuring that the team is actively taking care of the advisories and publishing or closing them depending on the applicability. +This verifies that a repository does not have untriaged security advisories +within a given severity threshold. Thus ensuring that the team is actively +taking care of the advisories and publishing or closing them depending on the +applicability. ## Linting -In order to enforce correctness and best practices for our rule types, we have a command-line utility called [mindev](https://github.com/mindersec/minder/tree/main/cmd/dev) that has a lint sub-command. +In order to enforce correctness and best practices for our rule types, we have a +command-line utility called +[mindev](https://github.com/mindersec/minder/tree/main/cmd/dev) that has a lint +sub-command. You can run it by doing the following from the Minder repository: @@ -321,12 +377,20 @@ You can run it by doing the following from the Minder repository: This will show you a list of suggestions to fix in your rule type definition. -The Styra team released a tool called [Regal](https://github.com/StyraInc/regal), which allows us to lint Rego policies for best practices or common issues. We embedded Regal into our own rule linting tool within mindev. So, running `mindev ruletype lint` on a rule type that leverages Rego will also show you OPA-related best practices. +The Styra team released a tool called +[Regal](https://github.com/StyraInc/regal), which allows us to lint Rego +policies for best practices or common issues. We embedded Regal into our own +rule linting tool within mindev. So, running `mindev ruletype lint` on a rule +type that leverages Rego will also show you OPA-related best practices. Conclusion -This introductory guide provides a foundation for leveraging Rego and Minder to write policies effectively. Experiment, explore, and tailor these techniques to meet the unique requirements of your projects. +This introductory guide provides a foundation for leveraging Rego and Minder to +write policies effectively. Experiment, explore, and tailor these techniques to +meet the unique requirements of your projects. -Minder is constantly evolving, so don’t be surprised if we soon add more custom functions or even more evaluation engines! The project is in full steam and more features are coming! +Minder is constantly evolving, so don’t be surprised if we soon add more custom +functions or even more evaluation engines! The project is in full steam and more +features are coming! [You can see a list of rule types that we actively maintain here.](https://github.com/mindersec/minder-rules-and-profiles) diff --git a/docs/docs/index.mdx b/docs/docs/index.mdx index 3585a4f63a..24a77e2b9f 100644 --- a/docs/docs/index.mdx +++ b/docs/docs/index.mdx @@ -7,7 +7,7 @@ import useBaseUrl from '@docusaurus/useBaseUrl'; import ThemedImage from '@theme/ThemedImage'; | | https://github.com/marketplace/actions/aqua-security-trivy | | | | +-------------+---------------------------------------------------------------------------------------+ -``` +```` -If the rule type is enabled and automatic remediation is configured, Minder will automatically create a pull request to enable Trivy scanning on your repository. +If the rule type is enabled and automatic remediation is configured, Minder will +automatically create a pull request to enable Trivy scanning on your repository. ## Dependabot -Dependabot is a tool that helps you keep your dependencies up to date. It automatically creates pull requests to update your dependencies when new versions are available. +Dependabot is a tool that helps you keep your dependencies up to date. It +automatically creates pull requests to update your dependencies when new +versions are available. -Minder integrates with Dependabot by providing a dedicated rule type that ensures that Dependabot is configured to run on your repositories. +Minder integrates with Dependabot by providing a dedicated rule type that +ensures that Dependabot is configured to run on your repositories. ```bash $ minder ruletype list @@ -115,18 +122,20 @@ $ minder ruletype get -i +-------------+----------------------------------------------------------------------------------------------------------------------------------+ ``` -If the rule type is enabled and automatic remediation is configured, Minder will automatically create a pull request to enable Dependabot on your repository. +If the rule type is enabled and automatic remediation is configured, Minder will +automatically create a pull request to enable Dependabot on your repository. -Note that you need to configure the ecosystem and package managers that dependabot should monitor. This is done by setting up -the relevant parameters in the rule definition in the profile. For example: +Note that you need to configure the ecosystem and package managers that +dependabot should monitor. This is done by setting up the relevant parameters in +the rule definition in the profile. For example: ```yaml --- version: v1 type: profile name: profile-with-dependabot -alert: "on" -remediate: "on" +alert: 'on' +remediate: 'on' repository: - type: dependabot_configured name: go_dependabot @@ -140,17 +149,22 @@ repository: apply_if_file: package.json ``` -In this example, we have two rules that configure Dependabot for Go and NPM packages. The `package_ecosystem` parameter specifies the package manager that -Dependabot should monitor, and the `apply_if_file` parameter specifies the file that should be present in the repository for the rule to apply. +In this example, we have two rules that configure Dependabot for Go and NPM +packages. The `package_ecosystem` parameter specifies the package manager that +Dependabot should monitor, and the `apply_if_file` parameter specifies the file +that should be present in the repository for the rule to apply. -The package ecosystem is anything that dependabot currently supports. For more information, see the +The package ecosystem is anything that dependabot currently supports. For more +information, see the [Dependabot documentation](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file). ## OSV (Open Source Vulnerabilities) -OSV is a vulnerability database and triage infrastructure for open source projects. It provides a curated list of vulnerabilities for open source projects -and is used by Minder to check for known vulnerabilities in your dependencies. Minder integrates with OSV by providing a dedicated rule type as well -as a dedicated integration point in the policy engine. +OSV is a vulnerability database and triage infrastructure for open source +projects. It provides a curated list of vulnerabilities for open source projects +and is used by Minder to check for known vulnerabilities in your dependencies. +Minder integrates with OSV by providing a dedicated rule type as well as a +dedicated integration point in the policy engine. ```bash $ minder ruletype list @@ -189,18 +203,25 @@ $ minder ruletype get -i +-------------+--------------------------------------------------------------------------------------------+ ``` -As the description and guidance say, this rule type applies to pull requests and checks if any new dependencies added in the pull request have known vulnerabilities. +As the description and guidance say, this rule type applies to pull requests and +checks if any new dependencies added in the pull request have known +vulnerabilities. -The rule type is evaluated using the `vulncheck` evaluation type, which is a custom evaluation type that checks the dependencies against the OSV database. -This is a direct minder integration, which means that there is custom code that fetches the vulnerabilities from the OSV database and -checks them against the dependencies in the pull request. It will also comment and propose changes to the pull request if any vulnerabilities are found. +The rule type is evaluated using the `vulncheck` evaluation type, which is a +custom evaluation type that checks the dependencies against the OSV database. +This is a direct minder integration, which means that there is custom code that +fetches the vulnerabilities from the OSV database and checks them against the +dependencies in the pull request. It will also comment and propose changes to +the pull request if any vulnerabilities are found. ## Conclusion -These were some of the open source tooling integrations that Minder supports. The policy engine is flexible enough to integrate with a variety of tools. -For more custom integrations, contact the Minder team at Stacklok. If you feel adventurous, you can also write your own rule types and integrations. +These were some of the open source tooling integrations that Minder supports. +The policy engine is flexible enough to integrate with a variety of tools. For +more custom integrations, contact the Minder team at Stacklok. If you feel +adventurous, you can also write your own rule types and integrations. Here are some resources to get you started: -* https://stacklok.com/blog/how-to-create-new-rule-types-in-minder-to-apply-custom-github-repo-security-settings -* https://stacklok.com/blog/writing-minder-rule-types-with-open-policy-agent-and-rego +- https://stacklok.com/blog/how-to-create-new-rule-types-in-minder-to-apply-custom-github-repo-security-settings +- https://stacklok.com/blog/writing-minder-rule-types-with-open-policy-agent-and-rego diff --git a/docs/docs/integrations/overview.md b/docs/docs/integrations/overview.md index de93c35735..5a6b67c65a 100644 --- a/docs/docs/integrations/overview.md +++ b/docs/docs/integrations/overview.md @@ -5,21 +5,25 @@ sidebar_position: 10 # Minder Integrations -Minder, as a platform, supports multiple integrations with different aspects of your supply chain, -as well as sources of information to make relevant decisions. +Minder, as a platform, supports multiple integrations with different aspects of +your supply chain, as well as sources of information to make relevant decisions. ## Providers -Providers are integrations with external services that provide information about your supply chain. +Providers are integrations with external services that provide information about +your supply chain. -Think of them as device drivers in an operating system. They provide a common interface to interact with different services. +Think of them as device drivers in an operating system. They provide a common +interface to interact with different services. -For more information, see the [Provider Integrations](provider_integrations/github.md) documentation. +For more information, see the +[Provider Integrations](provider_integrations/github.md) documentation. ## Integration with other tools -Minder is aims to be vendor neutral. That is, it doesn't care nor prefer one tool over the other. -It's designed to be flexible and integrate with the tools you already use. +Minder is aims to be vendor neutral. That is, it doesn't care nor prefer one +tool over the other. It's designed to be flexible and integrate with the tools +you already use. Examples of integrations include: @@ -27,13 +31,16 @@ Examples of integrations include: - CI/CD tools (e.g. GitHub Actions) - Automated dependency update tools (e.g. Dependabot) -For more information, see the [OSS Integrations](community_integrations.md) documentation. +For more information, see the [OSS Integrations](community_integrations.md) +documentation. ## Stacklok Insight -Stacklok Insight is a tool that helps you make better decisions about your dependencies. It provides a set -of heuristics to help you decide if a dependency is trustworthy or not. +Stacklok Insight is a tool that helps you make better decisions about your +dependencies. It provides a set of heuristics to help you decide if a dependency +is trustworthy or not. Stacklok Insight is integrated into Minder via a dedicated rule type. -For more information, see the [Stacklok Insight](stacklok-insight.md) documentation. +For more information, see the [Stacklok Insight](stacklok-insight.md) +documentation. diff --git a/docs/docs/integrations/provider_integrations/github.md b/docs/docs/integrations/provider_integrations/github.md index de35a71abc..e8046553ce 100644 --- a/docs/docs/integrations/provider_integrations/github.md +++ b/docs/docs/integrations/provider_integrations/github.md @@ -5,35 +5,42 @@ sidebar_position: 10 # Providers -A provider connects Minder to your software supply chain. It lets Minder know where to look for your repositories, artifacts, -and other entities are, in order to make them available for registration. It also tells Minder how to interact with your -supply chain to enable features such as alerting and remediation. Finally, it handles the way Minder authenticates -to the external service. +A provider connects Minder to your software supply chain. It lets Minder know +where to look for your repositories, artifacts, and other entities are, in order +to make them available for registration. It also tells Minder how to interact +with your supply chain to enable features such as alerting and remediation. +Finally, it handles the way Minder authenticates to the external service. The currently supported providers are: -* GitHub + +- GitHub Stay tuned as we add more providers in the future! ## Enrolling a provider To enroll GitHub as a provider, use the following command: + ``` minder provider enroll ``` -Once a provider is enrolled, public repositories from that provider can be registered with Minder. Security profiles -can then be applied to the registered repositories, giving you an overview of your security posture and providing +Once a provider is enrolled, public repositories from that provider can be +registered with Minder. Security profiles can then be applied to the registered +repositories, giving you an overview of your security posture and providing remediations to improve your security posture. ## Enrolling a provider with configuration -To specify provider configuration on enrollment, add the `--provider-config` flag and specify the path to the provider configuration file. For example: +To specify provider configuration on enrollment, add the `--provider-config` +flag and specify the path to the provider configuration file. For example: + ```bash minder provider enroll --provider-config /path/to/github-app-config.json ``` The provider configuration file should be a JSON file with the following format: + ```json { "github_app": {}, @@ -53,7 +60,9 @@ See the following section for provider configuration reference The GitHub App provider has the following configuration options: -* `auto_registration` (object): Configuration for the provider auto-registration feature - * `entities` (object): Configuration for auto-registering different entities - * `repository` (object): Configuration for auto-registering repositories - * `enabled` (boolean): Whether to auto-register repositories. Default is `false`. +- `auto_registration` (object): Configuration for the provider auto-registration + feature + - `entities` (object): Configuration for auto-registering different entities + - `repository` (object): Configuration for auto-registering repositories + - `enabled` (boolean): Whether to auto-register repositories. Default is + `false`. diff --git a/docs/docs/integrations/stacklok-insight.md b/docs/docs/integrations/stacklok-insight.md index 4c6b95ae39..d9cdbb1b64 100644 --- a/docs/docs/integrations/stacklok-insight.md +++ b/docs/docs/integrations/stacklok-insight.md @@ -5,25 +5,34 @@ sidebar_position: 40 # Stacklok Insight Integration -Minder integrates directly with [Stacklok Insight](http://insight.stacklok.com) to enable policy-driven dependency management based on the risk level of dependencies. +Minder integrates directly with [Stacklok Insight](http://insight.stacklok.com) +to enable policy-driven dependency management based on the risk level of +dependencies. -Minder provides a [Stacklok Insight rule type](../ref/rules/pr_trusty_check.md) which allows you to monitor new pull requests for newly added dependencies with risk indicators from [Stacklok Insight](https://insight.stacklok.com/). +Minder provides a [Stacklok Insight rule type](../ref/rules/pr_trusty_check.md) +which allows you to monitor new pull requests for newly added dependencies with +risk indicators from [Stacklok Insight](https://insight.stacklok.com/). -For every pull request submitted to a repository, this rule will check if the pull request adds a new dependency with -risk indicators from Stacklok Insight that exceed thresholds that you define. If a risky dependency is added, Minder will notify you and -suggest an alternative package, if one is available. +For every pull request submitted to a repository, this rule will check if the +pull request adds a new dependency with risk indicators from Stacklok Insight +that exceed thresholds that you define. If a risky dependency is added, Minder +will notify you and suggest an alternative package, if one is available. -Here we see Minder in action, commenting on a pull request that adds a package with risk indicators from Stacklok Insight: +Here we see Minder in action, commenting on a pull request that adds a package +with risk indicators from Stacklok Insight: ![Minder commenting on PR with Stacklok Insight risk signals](./low-trusty-score-pr.png) ## Create the rule type -Once you have [a Minder account](../getting_started/login.md), you can create a new rule of type `pr_trusty_check` to monitor your pull requests for untrustworthy packages. +Once you have [a Minder account](../getting_started/login.md), you can create a +new rule of type `pr_trusty_check` to monitor your pull requests for +untrustworthy packages. The rule type is one of the reference rule types provided by the Minder team. -Fetch all the reference rules by cloning the [minder-rules-and-profiles repository](https://github.com/mindersec/minder-rules-and-profiles). +Fetch all the reference rules by cloning the +[minder-rules-and-profiles repository](https://github.com/mindersec/minder-rules-and-profiles). ```bash git clone https://github.com/mindersec/minder-rules-and-profiles.git @@ -45,9 +54,15 @@ minder ruletype create -f rule-types/github/pr_trusty_check.yaml Next, create a profile that applies the rule to all registered repositories. -Create a new file called `stacklok-insight-risk-profile.yaml`. In this profile the following options are configured: -- `action` is set to `summary` allowing Minder to comment on pull requests with risk indicators from Stacklok Insight, providing an explanation of the issue and possible alternatives. -- `ecosystem_config` is set to check the `pypi` ecosystem for new dependencies whose Stacklok Insight activity score is below the threshold of 5.the threshold of 5. +Create a new file called `stacklok-insight-risk-profile.yaml`. In this profile +the following options are configured: + +- `action` is set to `summary` allowing Minder to comment on pull requests with + risk indicators from Stacklok Insight, providing an explanation of the issue + and possible alternatives. +- `ecosystem_config` is set to check the `pypi` ecosystem for new dependencies + whose Stacklok Insight activity score is below the threshold of 5.the + threshold of 5. ```yaml --- @@ -56,7 +71,7 @@ type: profile name: stacklok-insight-risk-profile context: provider: github -remediate: "on" +remediate: 'on' pull_request: - type: pr_trusty_check def: @@ -72,4 +87,5 @@ Create the profile in Minder: minder profile create -f stacklok-insight-risk-profile.yaml ``` -That's it! Any registered repos will now be monitored for new dependencies with risk indicators from Stacklok Insight. +That's it! Any registered repos will now be monitored for new dependencies with +risk indicators from Stacklok Insight. diff --git a/docs/docs/ref/cli_configuration.md b/docs/docs/ref/cli_configuration.md index 56d6647629..a00e7a46f5 100644 --- a/docs/docs/ref/cli_configuration.md +++ b/docs/docs/ref/cli_configuration.md @@ -1,26 +1,27 @@ # Minder CLI configuration -The Minder CLI application is configured using a YAML file. The default location for the configuration file -is `$PWD/config.yaml`. You can specify a different location using the `--config` flag. If there's no configuration -file at the specified location, the CLI application will use its default values. +The Minder CLI application is configured using a YAML file. The default location +for the configuration file is `$PWD/config.yaml`. You can specify a different +location using the `--config` flag. If there's no configuration file at the +specified location, the CLI application will use its default values. ## Prerequisites -* The `minder` CLI application -* A Stacklok account +- The `minder` CLI application +- A Stacklok account ## Configuration file example -Below is an example configuration file. The `grpc_server` section configures the gRPC server that the CLI -application will connect to. The `identity` section configures the issuer URL and client ID for the -Stacklok Identity service. +Below is an example configuration file. The `grpc_server` section configures the +gRPC server that the CLI application will connect to. The `identity` section +configures the issuer URL and client ID for the Stacklok Identity service. ```yaml --- # Minder CLI configuration # gRPC server configuration grpc_server: - host: "127.0.0.1" + host: '127.0.0.1' port: 8090 identity: @@ -30,17 +31,20 @@ identity: --- ``` -## Handle multiple contexts using a configuration file +## Handle multiple contexts using a configuration file -The Minder CLI can be configured to use multiple contexts. A context is a set of configuration values that -are used to define a context, i.e. connect to a specific Minder server. For example, you may have a context for your local -development environment, a context for your staging environment, and a context for your production -environment. You can also specify things like the default `provider`, `project` or preferred format `output` -for each of those. +The Minder CLI can be configured to use multiple contexts. A context is a set of +configuration values that are used to define a context, i.e. connect to a +specific Minder server. For example, you may have a context for your local +development environment, a context for your staging environment, and a context +for your production environment. You can also specify things like the default +`provider`, `project` or preferred format `output` for each of those. -To create a new context, create a new configuration file and set the `MINDER_CONFIG` environment variable -to point to the config file. For a single command, you can also set the path to the file through the `--config` -flag . For example, you can create your staging configuration in `config-staging.yaml` and use it as either: +To create a new context, create a new configuration file and set the +`MINDER_CONFIG` environment variable to point to the config file. For a single +command, you can also set the path to the file through the `--config` flag . For +example, you can create your staging configuration in `config-staging.yaml` and +use it as either: ```bash export MINDER_CONFIG=./config-staging.yaml diff --git a/docs/docs/ref/rules/artifact_signature.md b/docs/docs/ref/rules/artifact_signature.md index 5d5f222455..72402b304a 100644 --- a/docs/docs/ref/rules/artifact_signature.md +++ b/docs/docs/ref/rules/artifact_signature.md @@ -5,24 +5,34 @@ sidebar_position: 90 # Artifact signature verification -The following rule type is available for checking that an artifact has a valid signature -and its provenance conforms to a policy. +The following rule type is available for checking that an artifact has a valid +signature and its provenance conforms to a policy. ## `artifact_signature` - Verifies that an artifact has a valid signature -This rule allows you to verify that an artifact was signed and that the signature is valid. +This rule allows you to verify that an artifact was signed and that the +signature is valid. ## Entity + - `artifact` ## Type + - `artifact_signature` ## Rule Parameters -- `tags` - the tags that should be checked for signatures. If not specified, all tags will be checked. If specified, the artifact must be tagged with all of the specified tags in order to be checked. -- `tags_regex` - a regular expression specifying the tags that should be checked for signatures. If not specified, all tags will be checked. If specified, the artifact must be tagged with a tag that matches the regular expression in order to be checked. -- `name` - the name of the artifact that should be checked for signatures. If not specified, all artifacts will be checked. - + +- `tags` - the tags that should be checked for signatures. If not specified, all + tags will be checked. If specified, the artifact must be tagged with all of + the specified tags in order to be checked. +- `tags_regex` - a regular expression specifying the tags that should be checked + for signatures. If not specified, all tags will be checked. If specified, the + artifact must be tagged with a tag that matches the regular expression in + order to be checked. +- `name` - the name of the artifact that should be checked for signatures. If + not specified, all artifacts will be checked. + It is an error to specify both `tags` and `tags_regex`. ## Rule Definition Options @@ -33,6 +43,12 @@ The `artifact_signature` rule has the following options: - `is_verified` (bool): Whether the artifact's signature could be verified - `repository` (string): The repository that the artifact was built from - `branch` (string): The branch that the artifact was built from -- `signer_identity` (string): The identity of the signer of the artifact, e.g. a workflow name like `docker-image-build-push.yml` for GitHub workflow signatures or an email address -- `runner_environment` (string): The environment that the artifact was built in, i.e. hosted-runner or self-hosted-runner. Set to `github-hosted` to check for artifacts built on a GitHub-hosted runner. -- `cert_issuer` (string): The issuer of the certificate used to sign the artifact, i.e. `https://token.actions.githubusercontent.com` for GitHub Actions +- `signer_identity` (string): The identity of the signer of the artifact, e.g. a + workflow name like `docker-image-build-push.yml` for GitHub workflow + signatures or an email address +- `runner_environment` (string): The environment that the artifact was built in, + i.e. hosted-runner or self-hosted-runner. Set to `github-hosted` to check for + artifacts built on a GitHub-hosted runner. +- `cert_issuer` (string): The issuer of the certificate used to sign the + artifact, i.e. `https://token.actions.githubusercontent.com` for GitHub + Actions diff --git a/docs/docs/ref/rules/branch_protection.md b/docs/docs/ref/rules/branch_protection.md index e463592f4f..13e3abf833 100644 --- a/docs/docs/ref/rules/branch_protection.md +++ b/docs/docs/ref/rules/branch_protection.md @@ -4,79 +4,107 @@ sidebar_position: 10 --- # Branch Protection Rules + The following rule type is available for branch protection. ## `branch_protection_allow_deletions` - Whether the branch can be deleted -This rule allows you to allow users with push access to delete matching branches. +This rule allows you to allow users with push access to delete matching +branches. ### Entity + - `repository` ### Type + - `branch_protection_allow_deletions` ### Rule parameters + The `branch_protection_allow_deletions` rule supports the following parameters: + - `branch (string)` - The name of the branch to check. ### Rule definition options The `branch_protection_allow_deletions` rule supports the following options: -- `allow_deletions (boolean)` - Allows deletion of the protected branch by anyone with write access to the repository. + +- `allow_deletions (boolean)` - Allows deletion of the protected branch by + anyone with write access to the repository. ## `branch_protection_allow_force_pushes` - Whether force pushes are allowed to the branch This rule allows you to permit force pushes for all users with push access. ### Entity + - `repository` ### Type + - `branch_protection_allow_force_pushes` ### Rule parameters -The `branch_protection_allow_force_pushes` rule supports the following parameters: + +The `branch_protection_allow_force_pushes` rule supports the following +parameters: + - `branch (string)` - The name of the branch to check. ### Rule definition options The `branch_protection_allow_force_pushes` rule supports the following options: -- `allow_force_pushes (boolean)` - Permits force pushes to the protected branch by anyone with write access to the repository. + +- `allow_force_pushes (boolean)` - Permits force pushes to the protected branch + by anyone with write access to the repository. ## `branch_protection_allow_fork_syncing` - Whether users can pull changes from upstream when the branch is locked A locked branch cannot be pulled from. ### Entity + - `repository` ### Type + - `branch_protection_allow_fork_syncing` ### Rule parameters -The `branch_protection_allow_fork_syncing` rule supports the following parameters: + +The `branch_protection_allow_fork_syncing` rule supports the following +parameters: + - `branch (string)` - The name of the branch to check. ### Rule definition options The `branch_protection_allow_fork_syncing` rule supports the following options: -- `allow_fork_syncing (boolean)` - Whether users can pull changes from upstream when the branch is locked. Set to `true` to allow fork syncing. Set to `false` to prevent fork syncing. + +- `allow_fork_syncing (boolean)` - Whether users can pull changes from upstream + when the branch is locked. Set to `true` to allow fork syncing. Set to `false` + to prevent fork syncing. ## `branch_protection_enabled` - Verifies that a branch has a branch protection rule -You can protect important branches by setting branch protection rules, which define whether -collaborators can delete or force push to the branch and set requirements for any pushes to the branch, -such as passing status checks or a linear commit history. +You can protect important branches by setting branch protection rules, which +define whether collaborators can delete or force push to the branch and set +requirements for any pushes to the branch, such as passing status checks or a +linear commit history. ### Entity + - `repository` ### Type + - `branch_protection_enabled` ### Rule parameters + The `branch_protection_enabled` rule supports the following parameters: + - `branch (string)` - The name of the branch to check. ### Rule definition options @@ -88,177 +116,273 @@ The `branch_protection_enabled` rule supports the following parameters: Enforce required status checks for repository administrators. ### Entity + - `repository` ### Type + - `branch_protection_enforce_admins` ### Rule parameters + The `branch_protection_enforce_admins` rule supports the following parameters: + - `branch (string)` - The name of the branch to check. ### Rule definition options + The `branch_protection_enforce_admins` rule supports the following options: -- `enforce_admins (boolean)` - Specifies whether the protection rule applies to repository administrators. + +- `enforce_admins (boolean)` - Specifies whether the protection rule applies to + repository administrators. ## `branch_protection_lock_branch` - Whether the branch is locked -This rule allows you to set the branch as read-only. Users cannot push to the branch. +This rule allows you to set the branch as read-only. Users cannot push to the +branch. ### Entity + - `repository` ### Type + - `branch_protection_lock_branch` ### Rule parameters + The `branch_protection_lock_branch` rule supports the following parameters: + - `branch (string)` - The name of the branch to check. ### Rule definition options + The `branch_protection_lock_branch` rule supports the following options: -- `lock_branch (boolean)` - Whether to set the branch as read-only. If this is true, users will not be able to push to the branch. + +- `lock_branch (boolean)` - Whether to set the branch as read-only. If this is + true, users will not be able to push to the branch. ## `branch_protection_require_conversation_resolution` - Whether PR reviews must be resolved before merging -When enabled, all conversations on code must be resolved before a pull request can be merged into a branch that matches this rule. +When enabled, all conversations on code must be resolved before a pull request +can be merged into a branch that matches this rule. ### Entity + - `repository` ### Type + - `branch_protection_require_conversation_resolution` ### Rule parameters -The `branch_protection_require_conversation_resolution` rule supports the following parameters: + +The `branch_protection_require_conversation_resolution` rule supports the +following parameters: + - `branch (string)` - The name of the branch to check. ### Rule definition options -The `branch_protection_require_conversation_resolution` rule supports the following options: -- `required_conversation_resolution (boolean)` - Requires all conversations on code to be resolved before a pull request can be merged into a branch that matches this rule. + +The `branch_protection_require_conversation_resolution` rule supports the +following options: + +- `required_conversation_resolution (boolean)` - Requires all conversations on + code to be resolved before a pull request can be merged into a branch that + matches this rule. ## `branch_protection_require_linear_history` - Whether the branch requires a linear history with no merge commits -This rule allows you to prevent merge commits from being pushed to matching branches. +This rule allows you to prevent merge commits from being pushed to matching +branches. ### Entity + - `repository` ### Type + - `branch_protection_require_linear_history` ### Rule parameters -The `branch_protection_require_linear_history` rule supports the following parameters: + +The `branch_protection_require_linear_history` rule supports the following +parameters: + - `branch (string)` - The name of the branch to check. ### Rule definition options -The `branch_protection_require_linear_history` rule supports the following options: -- `required_linear_history (boolean)` - Enforces a linear commit Git history, which prevents anyone from pushing merge commits to a branch. + +The `branch_protection_require_linear_history` rule supports the following +options: + +- `required_linear_history (boolean)` - Enforces a linear commit Git history, + which prevents anyone from pushing merge commits to a branch. ## `branch_protection_require_pull_request_approving_review_count` - Require a certain number of approving reviews before merging -Each pull request must have a certain number of approving reviews before it can be merged into a matching branch. +Each pull request must have a certain number of approving reviews before it can +be merged into a matching branch. ### Entity + - `repository` ### Type + - `branch_protection_require_pull_request_approving_review_count` ### Rule parameters -The `branch_protection_require_pull_request_approving_review_count` rule supports the following parameters: + +The `branch_protection_require_pull_request_approving_review_count` rule +supports the following parameters: + - `branch (string)` - The name of the branch to check. ### Rule definition options -The `branch_protection_require_pull_request_approving_review_count` rule supports the following options: -- `required_approving_review_count (integer)` - Specify the number of reviewers required to approve pull requests. Use a number between 1 and 6 or 0 to not require reviewers. + +The `branch_protection_require_pull_request_approving_review_count` rule +supports the following options: + +- `required_approving_review_count (integer)` - Specify the number of reviewers + required to approve pull requests. Use a number between 1 and 6 or 0 to not + require reviewers. ## `branch_protection_require_pull_request_code_owners_review` - Verifies that a branch requires review from code owners -This rule allows you to require an approved review in pull requests including files with a designated code owner. +This rule allows you to require an approved review in pull requests including +files with a designated code owner. ### Entity + - `repository` ### Type + - `branch_protection_require_pull_request_code_owners_review` ### Rule parameters -The `branch_protection_require_pull_request_code_owners_review` rule supports the following parameters: + +The `branch_protection_require_pull_request_code_owners_review` rule supports +the following parameters: + - `branch (string)` - The name of the branch to check. ### Rule definition options -The `branch_protection_require_pull_request_code_owners_review` rule supports the following options: -- `require_code_owner_reviews (boolean)` - Set to true to require an approved review in pull requests including files with a designated code owner. + +The `branch_protection_require_pull_request_code_owners_review` rule supports +the following options: + +- `require_code_owner_reviews (boolean)` - Set to true to require an approved + review in pull requests including files with a designated code owner. ## `branch_protection_require_pull_request_dismiss_stale_reviews` - Require that new pushes to the branch dismiss old reviews -New reviewable commits pushed to a matching branch will dismiss pull request review approvals. +New reviewable commits pushed to a matching branch will dismiss pull request +review approvals. ### Entity + - `repository` ### Type + - `branch_protection_require_pull_request_dismiss_stale_reviews` ### Rule parameters -The `branch_protection_require_pull_request_dismiss_stale_reviews` rule supports the following parameters: + +The `branch_protection_require_pull_request_dismiss_stale_reviews` rule supports +the following parameters: + - `branch (string)` - The name of the branch to check. ### Rule definition options -The `branch_protection_require_pull_request_dismiss_stale_reviews` rule supports the following options: -- `dismiss_stale_reviews (boolean)` - Set to true to dismiss approving reviews when someone pushes a new commit. + +The `branch_protection_require_pull_request_dismiss_stale_reviews` rule supports +the following options: + +- `dismiss_stale_reviews (boolean)` - Set to true to dismiss approving reviews + when someone pushes a new commit. ## `branch_protection_require_pull_request_last_push_approval` - Require that the most recent push to a branch be approved by someone other than the person who pushed it -The most recent push to a branch must be approved by someone other than the person who pushed it. +The most recent push to a branch must be approved by someone other than the +person who pushed it. ### Entity + - `repository` ### Type + - `branch_protection_require_pull_request_last_push_approval` ### Rule parameters -The `branch_protection_require_pull_request_last_push_approval` rule supports the following parameters: + +The `branch_protection_require_pull_request_last_push_approval` rule supports +the following parameters: + - `branch (string)` - The name of the branch to check. ### Rule definition options -The `branch_protection_require_pull_request_last_push_approval` rule supports the following options: -- `require_last_push_approval (boolean)` - Whether the most recent push must be approved by someone other than the person who pushed it. + +The `branch_protection_require_pull_request_last_push_approval` rule supports +the following options: + +- `require_last_push_approval (boolean)` - Whether the most recent push must be + approved by someone other than the person who pushed it. ## `branch_protection_require_pull_requests` - Verifies that a branch requires pull requests -This rule allows you to require that a pull request be opened before merging to a branch. +This rule allows you to require that a pull request be opened before merging to +a branch. ### Entity + - `repository` ### Type + - `branch_protection_require_pull_requests` ### Rule parameters -The `branch_protection_require_pull_requests` rule supports the following parameters: + +The `branch_protection_require_pull_requests` rule supports the following +parameters: + - `branch (string)` - The name of the branch to check. ### Rule definition options -The `branch_protection_require_pull_requests` rule supports the following options: -- `required_pull_request_reviews (boolean)` - When enabled, all commits must be made to a non-protected branch and submitted via a pull request before they can be merged into a branch that matches this rule. + +The `branch_protection_require_pull_requests` rule supports the following +options: + +- `required_pull_request_reviews (boolean)` - When enabled, all commits must be + made to a non-protected branch and submitted via a pull request before they + can be merged into a branch that matches this rule. ## `branch_protection_require_signatures` - Whether commits to the branch must be signed Commits pushed to matching branches must have verified signatures. ### Entity + - `repository` ### Type + - `branch_protection_require_signatures` ### Rule parameters -The `branch_protection_require_signatures` rule supports the following parameters: + +The `branch_protection_require_signatures` rule supports the following +parameters: + - `branch (string)` - The name of the branch to check. ### Rule definition options + The `branch_protection_require_signatures` rule supports the following options: -- `required_signatures (boolean)` - Specifies whether commits to the branch must be signed. + +- `required_signatures (boolean)` - Specifies whether commits to the branch must + be signed. diff --git a/docs/docs/ref/rules/codeql_enabled.md b/docs/docs/ref/rules/codeql_enabled.md index a2372141d7..4055bbc55b 100644 --- a/docs/docs/ref/rules/codeql_enabled.md +++ b/docs/docs/ref/rules/codeql_enabled.md @@ -9,24 +9,32 @@ The following rule type is available for Code Scanning (CodeQL). ## `codeql_enabled` - Verifies that CodeQL is enabled for the repository -This rule allows you to monitor if code scanning via CodeQL is enabled for your repositories. -CodeQL is a tool that can be used to analyze code for security vulnerabilities. -It is recommended that repositories have some form of static analysis enabled -to ensure that vulnerabilities are not introduced into the codebase. +This rule allows you to monitor if code scanning via CodeQL is enabled for your +repositories. CodeQL is a tool that can be used to analyze code for security +vulnerabilities. It is recommended that repositories have some form of static +analysis enabled to ensure that vulnerabilities are not introduced into the +codebase. ### Entity + - `repository` ### Type + - `codeql_enabled` ### Rule parameters + - None ### Rule definition options The `codeql_enabled` rule supports the following options: -- `languages ([]string)` - Only applicable for remediation. Sets the CodeQL languages to use in the workflow. - - CodeQL supports `c-cpp`, `csharp`, `go`, `java-kotlin`, `javascript-typescript`, `python`, `ruby`, `swift` -- `schedule_interval (string, cron format)` - Only applicable for remediation. Sets the schedule interval for the workflow. - - Example: `20 14 * * 1` (every Monday at 2:20pm) + +- `languages ([]string)` - Only applicable for remediation. Sets the CodeQL + languages to use in the workflow. + - CodeQL supports `c-cpp`, `csharp`, `go`, `java-kotlin`, + `javascript-typescript`, `python`, `ruby`, `swift` +- `schedule_interval (string, cron format)` - Only applicable for remediation. + Sets the schedule interval for the workflow. + - Example: `20 14 * * 1` (every Monday at 2:20pm) diff --git a/docs/docs/ref/rules/dependabot_configured.md b/docs/docs/ref/rules/dependabot_configured.md index 94955c1c32..8c29efa514 100644 --- a/docs/docs/ref/rules/dependabot_configured.md +++ b/docs/docs/ref/rules/dependabot_configured.md @@ -9,25 +9,35 @@ The following rule type is available for Dependabot. ## `dependabot_configured` - Verifies that Dependabot is configured for the repository -This rule allows you to monitor if Dependabot is enabled for automated dependency updates for repositories. -It is recommended that repositories have some form of automated dependency updates enabled -to ensure that vulnerabilities are not introduced into the codebase. +This rule allows you to monitor if Dependabot is enabled for automated +dependency updates for repositories. It is recommended that repositories have +some form of automated dependency updates enabled to ensure that vulnerabilities +are not introduced into the codebase. ### Entity + - `repository` ### Type + - `dependabot_configured` ### Rule parameters + - None ### Rule definition options The `dependabot_configured` rule supports the following options: + - `package_ecosystem (string)` - The package ecosystem to check for updates - - The package ecosystem that the rule applies to. For example, `gomod`, `npm`, `docker`, `github-actions`, etc. + - The package ecosystem that the rule applies to. For example, `gomod`, `npm`, + `docker`, `github-actions`, etc. - `schedule_interval (string)` - The interval at which to check for updates - - The interval that the rule should be evaluated. For example, `daily`, `weekly`, `monthly`, etc. -- `apply_if_file (string)` - Optional. The file to check for to determine if the rule should be applied - - If specified, the rule will only be evaluated if the given file exists. This is useful for rules that are only applicable to certain types of repositories. \ No newline at end of file + - The interval that the rule should be evaluated. For example, `daily`, + `weekly`, `monthly`, etc. +- `apply_if_file (string)` - Optional. The file to check for to determine if the + rule should be applied + - If specified, the rule will only be evaluated if the given file exists. This + is useful for rules that are only applicable to certain types of + repositories. diff --git a/docs/docs/ref/rules/github_actions.md b/docs/docs/ref/rules/github_actions.md index 601d34e80d..7c740b1267 100644 --- a/docs/docs/ref/rules/github_actions.md +++ b/docs/docs/ref/rules/github_actions.md @@ -9,81 +9,107 @@ There are several rule types that can be used to configure GitHub Actions. ## `github_actions_allowed` - Which actions are allowed to be used -This rule allows you to limit the actions that are allowed to run for a repository. -It is recommended to use the `selected` option for allowed actions, and then -select the actions that are allowed to run. +This rule allows you to limit the actions that are allowed to run for a +repository. It is recommended to use the `selected` option for allowed actions, +and then select the actions that are allowed to run. ### Entity + - `repository` ### Type + - `github_actions_allowed` ### Rule parameters + - None ### Rule definition options The `github_actions_allowed` rule supports the following options: + - `allowed_actions (enum)` - Which actions are allowed to be used - - `all` - Any action or reusable workflow can be used, regardless of who authored it or where it is defined. - - `local_only` - Only actions and reusable workflows that are defined in the repository or organization can be used. - - `selected` - Only the actions and reusable workflows that are explicitly listed are allowed. Use the `allowed_selected_actions` `rule_type` to set the list of allowed actions. + - `all` - Any action or reusable workflow can be used, regardless of who + authored it or where it is defined. + - `local_only` - Only actions and reusable workflows that are defined in the + repository or organization can be used. + - `selected` - Only the actions and reusable workflows that are explicitly + listed are allowed. Use the `allowed_selected_actions` `rule_type` to set + the list of allowed actions. ## `allowed_selected_actions` - Verifies that only allowed actions are used -To use this rule, the repository profile for `github_actions_allowed` must -be configured to `selected`. +To use this rule, the repository profile for `github_actions_allowed` must be +configured to `selected`. ### Entity + - `repository` ### Type + - `allowed_selected_actions` ### Rule parameters + - None ### Rule definition options The `allowed_selected_actions` rule supports the following options: -- `github_owner_allowed (boolean)` - Whether GitHub-owned actions are allowed. For example, this includes the actions in the `actions` organization. -- `verified_allowed (boolean)` - Whether actions that are verified by GitHub are allowed. -- `patterns_allowed (boolean)` - Specifies a list of string-matching patterns to allow specific action(s) and reusable workflow(s). Wildcards, tags, and SHAs are allowed. + +- `github_owner_allowed (boolean)` - Whether GitHub-owned actions are allowed. + For example, this includes the actions in the `actions` organization. +- `verified_allowed (boolean)` - Whether actions that are verified by GitHub are + allowed. +- `patterns_allowed (boolean)` - Specifies a list of string-matching patterns to + allow specific action(s) and reusable workflow(s). Wildcards, tags, and SHAs + are allowed. ## `default_workflow_permissions` - Sets the default permissions granted to the `GITHUB_TOKEN` when running workflows -Verifies the default workflow permissions granted to the GITHUB_TOKEN -when running workflows in a repository, as well as if GitHub Actions -can submit approving pull request reviews. +Verifies the default workflow permissions granted to the GITHUB_TOKEN when +running workflows in a repository, as well as if GitHub Actions can submit +approving pull request reviews. ### Entity + - `repository` ### Type + - `default_workflow_permissions` ### Rule parameters + - None ### Rule definition options The `default_workflow_permissions` rule supports the following options: -- `default_workflow_permissions (boolean)` - Whether GitHub-owned actions are allowed. For example, this includes the actions in the `actions` organization. -- `can_approve_pull_request_reviews (boolean)` - Whether the `GITHUB_TOKEN` can approve pull request reviews. + +- `default_workflow_permissions (boolean)` - Whether GitHub-owned actions are + allowed. For example, this includes the actions in the `actions` organization. +- `can_approve_pull_request_reviews (boolean)` - Whether the `GITHUB_TOKEN` can + approve pull request reviews. ## `actions_check_pinned_tags` - Verifies that any actions use pinned tags Verifies that actions use pinned tags as opposed to floating tags. ### Entity + - `repository` ### Type + - `actions_check_pinned_tags` ### Rule parameters + - None ### Rule definition options + - None diff --git a/docs/docs/ref/rules/license.md b/docs/docs/ref/rules/license.md index e1cf9efe6a..0a1df65f55 100644 --- a/docs/docs/ref/rules/license.md +++ b/docs/docs/ref/rules/license.md @@ -5,26 +5,34 @@ sidebar_position: 80 # Presence of a License File Rule -The following rule type is available for verifying if a license file is present and it is of a certain type. +The following rule type is available for verifying if a license file is present +and it is of a certain type. ## `license` - Verifies if there is a license file of a given type present in the repository -This rule allows you to monitor if a license file is present in the repository and if its license type complies with -the configured license type in your profile. +This rule allows you to monitor if a license file is present in the repository +and if its license type complies with the configured license type in your +profile. ### Entity + - `repository` ### Type + - `license` ### Rule parameters + - None ### Rule definition options The `license` rule supports the following options: + - `license_filename (string)` - The license filename to look for. - - Example: `LICENSE`, `LICENSE.txt`, `LICENSE.md`, etc. + - Example: `LICENSE`, `LICENSE.txt`, `LICENSE.md`, etc. - `license_type (string)` - The license type to look for in `license_filename`. - - Example: `MIT`, `Apache`, etc. See [SPDX License List](https://spdx.org/licenses/) for a list of license types. Leave `""` to only check for the presence of the file. + - Example: `MIT`, `Apache`, etc. See + [SPDX License List](https://spdx.org/licenses/) for a list of license types. + Leave `""` to only check for the presence of the file. diff --git a/docs/docs/ref/rules/pr_trusty_check.md b/docs/docs/ref/rules/pr_trusty_check.md index e09afe05f1..f896836b8d 100644 --- a/docs/docs/ref/rules/pr_trusty_check.md +++ b/docs/docs/ref/rules/pr_trusty_check.md @@ -5,37 +5,56 @@ sidebar_position: 20 # Stacklok Insight Rule -The following rule type is available to check dependency risk with [Stacklok Insight](https://insight.stacklok.com/). +The following rule type is available to check dependency risk with +[Stacklok Insight](https://insight.stacklok.com/). ## `pr_trusty_check` - Verifies that pull requests do not add any dependencies with risk indicators from Stacklok Insight -This rule allows you to monitor new pull requests for newly added dependencies with risk indicators from -[Stacklok Insight](https://insight.stacklok.com/). -For every pull request submitted to a repository, this rule will check any software +This rule allows you to monitor new pull requests for newly added dependencies +with risk indicators from [Stacklok Insight](https://insight.stacklok.com/). For +every pull request submitted to a repository, this rule will check any software dependencies for the supported ecosystems and flag any problems found with them. -Based on the Stacklok Insight data, Minder can block the PR or mark the policy as failed. +Based on the Stacklok Insight data, Minder can block the PR or mark the policy +as failed. ## Entity + - `pull_request` ## Type + - `pr_trusty_check` ## Rule Parameters + - None ## Rule Definition Options The `pr_trusty_check` rule supports the following options: -- `action` (string): The action to take if a risky package is found. Valid values are: - - `summary`: The evaluator engine will add a single summary comment with a table listing risky packages found - - `profile_only`: The evaluator engine will merely pass on an error, marking the profile as failed if a risky package is found - - `review`: The trusty evaluator will add a review asking for changes when problematic dependencies are found. Use the review action to block any pull requests introducing dependencies that break the policy established defined by the rule. -- `ecosystem_config`: An array of ecosystem configurations to check. Each ecosystem configuration has the following options: - - `name` (string): The name of the ecosystem to check. Currently `npm` and `pypi` are supported. - - `score (integer)`: DEPRECATED - this score is deprecated and only remains for backward compatibility. It always returns a value of `0`. We recommend setting this option to `0` and using the other options to control this rule's behavior. - - `provenance` (number): Minimum provenance score to consider a package's proof of origin satisfactory. +- `action` (string): The action to take if a risky package is found. Valid + values are: + - `summary`: The evaluator engine will add a single summary comment with a + table listing risky packages found + - `profile_only`: The evaluator engine will merely pass on an error, marking + the profile as failed if a risky package is found + - `review`: The trusty evaluator will add a review asking for changes when + problematic dependencies are found. Use the review action to block any pull + requests introducing dependencies that break the policy established defined + by the rule. +- `ecosystem_config`: An array of ecosystem configurations to check. Each + ecosystem configuration has the following options: + - `name` (string): The name of the ecosystem to check. Currently `npm` and + `pypi` are supported. + - `score (integer)`: DEPRECATED - this score is deprecated and only remains + for backward compatibility. It always returns a value of `0`. We recommend + setting this option to `0` and using the other options to control this + rule's behavior. + - `provenance` (number): Minimum provenance score to consider a package's + proof of origin satisfactory. - `activity` (number): Minimum activity score to consider a package as active. - - `allow_malicious` (boolean): Don't raise an error when a PR introduces dependencies known to be malicious (not recommended) - - `allow_deprecated` (boolean): Don't block when a pull request introduces dependencies marked as deprecated upstream. + - `allow_malicious` (boolean): Don't raise an error when a PR introduces + dependencies known to be malicious (not recommended) + - `allow_deprecated` (boolean): Don't block when a pull request introduces + dependencies marked as deprecated upstream. diff --git a/docs/docs/ref/rules/pr_vulnerability_check.md b/docs/docs/ref/rules/pr_vulnerability_check.md index 5ed65fa5f5..4365e779d0 100644 --- a/docs/docs/ref/rules/pr_vulnerability_check.md +++ b/docs/docs/ref/rules/pr_vulnerability_check.md @@ -9,45 +9,64 @@ The following rule type is available for known vulnerabilities. ## `pr_vulnerability_check` - Verifies that pull requests do not add dependencies with known vulnerabilities -For every pull request submitted to a repository, this rule will check if the pull request -adds a new dependency with known vulnerabilities based on the [OSV database](https://osv.dev/). If it does, the rule will fail and the -pull request will be rejected or commented on. +For every pull request submitted to a repository, this rule will check if the +pull request adds a new dependency with known vulnerabilities based on the +[OSV database](https://osv.dev/). If it does, the rule will fail and the pull +request will be rejected or commented on. ### Entity - - `pull_request` + +- `pull_request` ### Type - - `pr_vulnerability_check` + +- `pr_vulnerability_check` ### Rule Parameters - - None + +- None ### Rule Definition Options The `pr_vulnerability_check` rule has the following options: -- `action` (string): The action to take if a vulnerability is found. Valid values are: - - `review`: Minder will review the PR, suggest changes and mark the PR as changes requested if a vulnerability is found - - `commit_status`: Minder will comment and suggest changes on the PR if a vulnerability is found. Additionally, Minder - will set the commit_status of the PR `HEAD` to `failed` to prevent the commit from being merged - - `comment`: Minder will comment and suggest changes on the PR if a vulnerability is found, but not request changes - - `summary`: The evaluator engine will add a single summary comment with a table listing the vulnerabilities found - - `profile_only`: The evaluator engine will merely pass on an error, marking the profile as failed if a vulnerability is found -- `ecosystem_config`: An array of ecosystem configurations to check. Each ecosystem configuration has the following options: - - `name` (string): The name of the ecosystem to check. Currently `npm`, `go` and `pypi` are supported. - - `vulnerability_database_type` (string): The kind of vulnerability database to use. Currently only `osv` is supported. - - `vulnerability_database_endpoint` (string): The endpoint of the vulnerability database to use. - - `package_repository`: The package repository to use. This is an object with the following options: - - `url` (string): The URL of the package repository to use. Only the `go` ecosystem uses this option. - - `sum_repository`: The Go sum repository to use. This is an object with the following options: - - `url` (string): The URL of the Go sum repository to use. - -Note that if the `review` action is selected, `minder` will only be able to mark the PR as changes requested if the submitter -is not the same as the Minder identity. If the submitter is the same as the -Minder identity, the PR will only be commented on. - -Also note that if `commit_status` action is selected, the PR can only be prevented from merging if the branch protection rules -are set to require a passing commit status. +- `action` (string): The action to take if a vulnerability is found. Valid + values are: + - `review`: Minder will review the PR, suggest changes and mark the PR as + changes requested if a vulnerability is found + - `commit_status`: Minder will comment and suggest changes on the PR if a + vulnerability is found. Additionally, Minder will set the commit_status of + the PR `HEAD` to `failed` to prevent the commit from being merged + - `comment`: Minder will comment and suggest changes on the PR if a + vulnerability is found, but not request changes + - `summary`: The evaluator engine will add a single summary comment with a + table listing the vulnerabilities found + - `profile_only`: The evaluator engine will merely pass on an error, marking + the profile as failed if a vulnerability is found +- `ecosystem_config`: An array of ecosystem configurations to check. Each + ecosystem configuration has the following options: + - `name` (string): The name of the ecosystem to check. Currently `npm`, `go` + and `pypi` are supported. + - `vulnerability_database_type` (string): The kind of vulnerability database + to use. Currently only `osv` is supported. + - `vulnerability_database_endpoint` (string): The endpoint of the + vulnerability database to use. + - `package_repository`: The package repository to use. This is an object with + the following options: + - `url` (string): The URL of the package repository to use. Only the `go` + ecosystem uses this option. + - `sum_repository`: The Go sum repository to use. This is an object with the + following options: + - `url` (string): The URL of the Go sum repository to use. + +Note that if the `review` action is selected, `minder` will only be able to mark +the PR as changes requested if the submitter is not the same as the Minder +identity. If the submitter is the same as the Minder identity, the PR will only +be commented on. + +Also note that if `commit_status` action is selected, the PR can only be +prevented from merging if the branch protection rules are set to require a +passing commit status. ### Examples @@ -56,21 +75,21 @@ are set to require a passing commit status. def: action: review ecosystem_config: - - name: npm - vulnerability_database_type: osv - vulnerability_database_endpoint: https://api.osv.dev/v1/query - package_repository: - url: https://registry.npmjs.org - - name: go - vulnerability_database_type: osv - vulnerability_database_endpoint: https://api.osv.dev/v1/query - package_repository: - url: https://proxy.golang.org - sum_repository: - url: https://sum.golang.org - - name: pypi - vulnerability_database_type: osv - vulnerability_database_endpoint: https://api.osv.dev/v1/query - package_repository: - url: https://pypi.org/pypi + - name: npm + vulnerability_database_type: osv + vulnerability_database_endpoint: https://api.osv.dev/v1/query + package_repository: + url: https://registry.npmjs.org + - name: go + vulnerability_database_type: osv + vulnerability_database_endpoint: https://api.osv.dev/v1/query + package_repository: + url: https://proxy.golang.org + sum_repository: + url: https://sum.golang.org + - name: pypi + vulnerability_database_type: osv + vulnerability_database_endpoint: https://api.osv.dev/v1/query + package_repository: + url: https://pypi.org/pypi ``` diff --git a/docs/docs/ref/rules/secret_scanning.md b/docs/docs/ref/rules/secret_scanning.md index 4cf6cf5a7a..0151e85968 100644 --- a/docs/docs/ref/rules/secret_scanning.md +++ b/docs/docs/ref/rules/secret_scanning.md @@ -9,20 +9,25 @@ The following rule type is available for secret scanning. ## `secret_scanning` - Verifies that secret scanning is enabled for a given repository -Secret scanning is a feature that scans repositories for secrets and alerts -the repository owner when a secret is found. To enable this feature in GitHub, -you must enable it in the repository settings. +Secret scanning is a feature that scans repositories for secrets and alerts the +repository owner when a secret is found. To enable this feature in GitHub, you +must enable it in the repository settings. ### Entity + - `repository` ### Type + - `secret_scanning` ### Rule parameters + - None ### Rule definition options The `secret_scanning` rule supports the following options: -- `enabled (boolean)` - Whether secret scanning should be enabled for a given repository. + +- `enabled (boolean)` - Whether secret scanning should be enabled for a given + repository. diff --git a/docs/docs/run_minder_server/config_oauth.md b/docs/docs/run_minder_server/config_oauth.md index 91f0afa0b5..155a77f9a2 100644 --- a/docs/docs/run_minder_server/config_oauth.md +++ b/docs/docs/run_minder_server/config_oauth.md @@ -1,17 +1,16 @@ --- -title: Create a GitHub OAuth Application +title: Create a GitHub OAuth Application sidebar_position: 120 --- - ## Prerequisites - [GitHub](https://github.com) account ## Steps - -A legacy method for allowing users to enroll into Minder is using a GitHub OAuth application. +A legacy method for allowing users to enroll into Minder is using a GitHub OAuth +application. 1. Navigate to [GitHub Developer Settings](https://github.com/settings/profile) 2. Select "Developer Settings" from the left hand menu @@ -20,11 +19,13 @@ A legacy method for allowing users to enroll into Minder is using a GitHub OAuth 5. Enter the following details: - Application Name: `Minder` (or any other name you like) - Homepage URL: `http://localhost:8080` - - Authorization callback URL: `http://localhost:8080/api/v1/auth/callback/github` - - If you are prompted to enter a `Webhook URL`, deselect the `Active` option in the `Webhook` section. + - Authorization callback URL: + `http://localhost:8080/api/v1/auth/callback/github` + - If you are prompted to enter a `Webhook URL`, deselect the `Active` option + in the `Webhook` section. 6. Select "Register Application" 7. Generate a client secret -7. Copy the "Client ID" , "Client Secret" and "Authorization callback URL" values - into your `./server-config.yaml` file, under the `github` section. +8. Copy the "Client ID" , "Client Secret" and "Authorization callback URL" + values into your `./server-config.yaml` file, under the `github` section. -![github oauth2 page](./images/minder-server-oauth.png) \ No newline at end of file +![github oauth2 page](./images/minder-server-oauth.png) diff --git a/docs/docs/run_minder_server/config_provider.md b/docs/docs/run_minder_server/config_provider.md index d180cd5ac3..cd7aaaecdf 100644 --- a/docs/docs/run_minder_server/config_provider.md +++ b/docs/docs/run_minder_server/config_provider.md @@ -4,20 +4,26 @@ sidebar_position: 20 --- # Configuring a Provider -A provider connects Minder to your software supply chain — giving Minder information about your source code repositories, and their pull requests, dependencies, and artifacts. + +A provider connects Minder to your software supply chain — giving Minder +information about your source code repositories, and their pull requests, +dependencies, and artifacts. The currently supported providers are: -- GitHub -For GitHub, you configure a Provider by creating a GitHub App. +- GitHub + +For GitHub, you configure a Provider by creating a GitHub App. ## Prerequisites - [GitHub](https://github.com) account ## Create a GitHub App -This approach allows fine-grained control over the permissions that Minder has in users' repositories. It also -allows users to limit the repositories that Minder can access. + +This approach allows fine-grained control over the permissions that Minder has +in users' repositories. It also allows users to limit the repositories that +Minder can access. 1. Navigate to [GitHub Developer Settings](https://github.com/settings/profile) 1. Select "Developer Settings" from the left hand menu @@ -27,44 +33,57 @@ allows users to limit the repositories that Minder can access. ![Adding a new GitHub App](./images/new-github-app.png) ### Basic Information + Complete the following fields: - - GitHub App Name: `My Minder App` (or any other name you like) - - Homepage URL: `http://localhost:8080` + +- GitHub App Name: `My Minder App` (or any other name you like) +- Homepage URL: `http://localhost:8080` ![Basic fields](./images/provider-basic.png) ### Identifying and authorizing users + Complete the following fields: - - Callback URL: `http://localhost:8080/api/v1/auth/callback/github-app/app` - - Add an additional Callback URL for Keycloak: `http://localhost:8081/realms/stacklok/broker/github/endpoint` - - Select the checkbox for "Request user authorization (OAuth) during installation" + +- Callback URL: `http://localhost:8080/api/v1/auth/callback/github-app/app` +- Add an additional Callback URL for Keycloak: + `http://localhost:8081/realms/stacklok/broker/github/endpoint` +- Select the checkbox for "Request user authorization (OAuth) during + installation" ![Configuring the GitHub Provider](./images/provider-ident-and-auth.png) ### Webhook + - Under Webhook, uncheck Active ### Permissions + Select the following permissions: - - Repository Permissions: - - Administration (read and write) - - Contents (read and write) - - Metadata (read only) - - Packages (read and write) - - Pull requests (read and write) - - Repository security advisories (read and write) - - Webhooks (read and write) - - Workflows (read and write) - - Account permissions: - - Email addresses (read only) +- Repository Permissions: -Once completed, double check your selected numbers match the ones in the screenshot. + - Administration (read and write) + - Contents (read and write) + - Metadata (read only) + - Packages (read and write) + - Pull requests (read and write) + - Repository security advisories (read and write) + - Webhooks (read and write) + - Workflows (read and write) + +- Account permissions: + - Email addresses (read only) + +Once completed, double check your selected numbers match the ones in the +screenshot. ![Permissions](./images/provider-permissions.png) ### Installation and Scope + For the option "Where can this GitHub App be installed?": + - Select "Any account" if you want to allow any GitHub user to install the app - Or, select "Only on this account" to restrict the app to only your account. @@ -73,74 +92,90 @@ Then select "Create GitHub App" to create the App. ![Permissions](./images/provider-create.png) ### Generate a client secret -You should now have a GitHub App created. You now need to create a `Client secret` for authentication. -Click the `Generate a new client secret button`. + +You should now have a GitHub App created. You now need to create a +`Client secret` for authentication. Click the +`Generate a new client secret button`. ![Client secret](./images/provider-client-secret-created.png) -Save the Client secret value for use in the Configure Minder step. +Save the Client secret value for use in the Configure Minder step. + +### Generate a private key -### Generate a private key Scroll down to the bottom of the page and generate a private key. ![Generate a private key](./images/provider-generate-private.png) -This will generate and download your private key. -Now we need to move and rename the private key. -Run the following commands from the Minder root directory, replacing `` with the path to the downloaded private key. +This will generate and download your private key. Now we need to move and rename +the private key. Run the following commands from the Minder root directory, +replacing `` with the path to the downloaded private key. + ```bash mkdir .secrets cp .secrets/github-app.pem ``` ## Configure the Minder server -Now that we've created our GitHub App, we need to configure the Minder server to use it. +Now that we've created our GitHub App, we need to configure the Minder server to +use it. ### Add GitHub App configuration -In your `server-config.yaml` file, located in the root Minder directory, find the following section: +In your `server-config.yaml` file, located in the root Minder directory, find +the following section: + ```yaml github-app: - client_id: "client-id" - client_secret: "client-secret" - redirect_uri: "http://localhost:8080/api/v1/auth/callback/github-app/app" # This needs to match the registered callback URL in the GitHub App + client_id: 'client-id' + client_secret: 'client-secret' + redirect_uri: 'http://localhost:8080/api/v1/auth/callback/github-app/app' # This needs to match the registered callback URL in the GitHub App ``` + Update the `client_id` and `client_secret` values with the following: -- Client ID : Found in the General -> About section of your GitHub App on GitHub. + +- Client ID : Found in the General -> About section of your GitHub App on + GitHub. ![Client ID](./images/provider-client-id.png) -- Client Secret : The value you saved previously. +- Client Secret : The value you saved previously. ### Add Provider configuration + Then, find the following section in the same `server-config.yaml` file: ```yaml provider: github-app: - app_name: "app-name" + app_name: 'app-name' app_id: 1234 user_id: 1234 - private_key: ".secrets/github-app.pem" + private_key: '.secrets/github-app.pem' ``` -Update the `app_name` with the name of your app, which you can get by looking at the GitHub URL when editing your GitHub App. For example, if the URL is https://github.com/settings/apps/my-test-app, then your app name is my-test-app. + +Update the `app_name` with the name of your app, which you can get by looking at +the GitHub URL when editing your GitHub App. For example, if the URL is +https://github.com/settings/apps/my-test-app, then your app name is my-test-app. ![App name](./images/provider-app-name.png) -Update `app_id` with the app ID of your GitHub App, which is found in the General -> About section of your GitHub App on GitHub. +Update `app_id` with the app ID of your GitHub App, which is found in the +General -> About section of your GitHub App on GitHub. ![App ID](./images/provider-app-id.png) -Finally, you need the `user_id` value. To get the value, run the following command, where `` is the App name you used above: +Finally, you need the `user_id` value. To get the value, run the following +command, where `` is the App name you used above: ```bash curl https://api.github.com/users/%5Bbot%5D ``` + Update the `user_id` value with the `id` value returned from that command. ![User ID](./images/provider-user-id.png) -Now save the file. Your Provider is now created and the Minder server is configured to use it. - - +Now save the file. Your Provider is now created and the Minder server is +configured to use it. diff --git a/docs/docs/run_minder_server/config_webhook.md b/docs/docs/run_minder_server/config_webhook.md index 470335fec2..26545e0e59 100644 --- a/docs/docs/run_minder_server/config_webhook.md +++ b/docs/docs/run_minder_server/config_webhook.md @@ -4,44 +4,53 @@ sidebar_position: 70 --- # Configuring a Webhook -Minder allows a webhook to be configured on the repository provider to respond to provider events. Currently, Minder only supports GitHub. -The webhook allows GitHub to notify Minder when certain events occur in your repositories. -To configure the webhook, Minder needs to be accessible from the internet. If you are running the server locally, you -can use a service like [ngrok](https://ngrok.com/) to expose your local server to the internet. + +Minder allows a webhook to be configured on the repository provider to respond +to provider events. Currently, Minder only supports GitHub. The webhook allows +GitHub to notify Minder when certain events occur in your repositories. To +configure the webhook, Minder needs to be accessible from the internet. If you +are running the server locally, you can use a service like +[ngrok](https://ngrok.com/) to expose your local server to the internet. Here are the steps to configure the webhook: -1. **Expose your local server:** If you are running the server locally, start ngrok or a similar service to expose your -local server to the internet. Note down the URL provided by ngrok (it will look something like `https://.ngrok.io`). -Make sure to expose the port that Minder is running on (by default, this is port `8080`). +1. **Expose your local server:** If you are running the server locally, start + ngrok or a similar service to expose your local server to the internet. Note + down the URL provided by ngrok (it will look something like + `https://.ngrok.io`). Make sure to expose the port that Minder + is running on (by default, this is port `8080`). -2. **Update the Minder configuration:** Open your `server-config.yaml` file and update the `webhook-config` section with -the ngrok URL Minder is running on. The `external_webhook_url` should point to the `/api/v1/webhook/github` -endpoint on your Minder server, and the `external_ping_url` should point to the `/api/v1/health` endpoint. The `webhook_secret` -should match the secret configured in the GitHub webhook (under `github.payload_secret`). +2. **Update the Minder configuration:** Open your `server-config.yaml` file and + update the `webhook-config` section with the ngrok URL Minder is running on. + The `external_webhook_url` should point to the `/api/v1/webhook/github` + endpoint on your Minder server, and the `external_ping_url` should point to + the `/api/v1/health` endpoint. The `webhook_secret` should match the secret + configured in the GitHub webhook (under `github.payload_secret`). ```yaml webhook-config: - external_webhook_url: "https:///api/v1/webhook/github" - external_ping_url: "https:///api/v1/health" - webhook_secret: "your-password" # Should match the secret configured in the GitHub webhook (github.payload_secret) + external_webhook_url: 'https:///api/v1/webhook/github' + external_ping_url: 'https:///api/v1/health' + webhook_secret: 'your-password' # Should match the secret configured in the GitHub webhook (github.payload_secret) ``` -After these steps, your Minder server should be ready to receive webhook events from GitHub, and add webhooks to repositories. +After these steps, your Minder server should be ready to receive webhook events +from GitHub, and add webhooks to repositories. -In case you need to update the webhook secret, you can do so by putting the -new secret in `webhook-config.webhook_secret` and for the duration of the -migration, the old secret(s) in a file referenced by -`webhook-config.previous_webhook_secret_file`. The old webhook secrets will -then only be used to verify incoming webhooks messages, not for creating or -updating webhooks and can be removed after the migration is complete. +In case you need to update the webhook secret, you can do so by putting the new +secret in `webhook-config.webhook_secret` and for the duration of the migration, +the old secret(s) in a file referenced by +`webhook-config.previous_webhook_secret_file`. The old webhook secrets will then +only be used to verify incoming webhooks messages, not for creating or updating +webhooks and can be removed after the migration is complete. -In order to rotate webhook secrets, you can use the `minder-server` CLI tool to update the webhook secret. +In order to rotate webhook secrets, you can use the `minder-server` CLI tool to +update the webhook secret. ```bash minder-server webhook update -p github ``` -Note that the command simply replaces the webhook secret on the provider -side. You will still need to update the webhook secret in the server configuration -to match the provider's secret. \ No newline at end of file +Note that the command simply replaces the webhook secret on the provider side. +You will still need to update the webhook secret in the server configuration to +match the provider's secret. diff --git a/docs/docs/run_minder_server/installing_minder.md b/docs/docs/run_minder_server/installing_minder.md index a30b312cf7..68fedcceff 100644 --- a/docs/docs/run_minder_server/installing_minder.md +++ b/docs/docs/run_minder_server/installing_minder.md @@ -6,85 +6,120 @@ sidebar_position: 80 # Installing Minder with Helm ## Keycloak Installation -Minder is designed to operate without storing user credentials or personal information. To achieve this, it relies on an external identity provider. While Minder is compatible with any OpenID Connect (OIDC)-enabled identity provider, we have thoroughly tested it with Keycloak and thus recommend it for a seamless integration. + +Minder is designed to operate without storing user credentials or personal +information. To achieve this, it relies on an external identity provider. While +Minder is compatible with any OpenID Connect (OIDC)-enabled identity provider, +we have thoroughly tested it with Keycloak and thus recommend it for a seamless +integration. ### Getting Started with Keycloak -To install Keycloak as your identity provider, please refer to the following resources for detailed instructions: -- Keycloak Operator Installation Guide: [Keycloak Operator Installation](https://www.keycloak.org/operator/installation) -- Keycloak Tutorials for Beginners: [Keycloak Tutorials](https://keycloak.ch/keycloak-tutorials/tutorial-1-installing-and-running-keycloak/) +To install Keycloak as your identity provider, please refer to the following +resources for detailed instructions: + +- Keycloak Operator Installation Guide: + [Keycloak Operator Installation](https://www.keycloak.org/operator/installation) +- Keycloak Tutorials for Beginners: + [Keycloak Tutorials](https://keycloak.ch/keycloak-tutorials/tutorial-1-installing-and-running-keycloak/) -After the installation of Keycloak, there are specific settings and configurations required for Minder to function properly: +After the installation of Keycloak, there are specific settings and +configurations required for Minder to function properly: -1) **Realm Configuration:** Set up a dedicated realm in Keycloak for Minder's use. -2) **Client Setup:** Create two separate clients within the realm: - - **minder-cli:** A client for command-line interactions. - - **minder-server:** A client for server-side operations. -3) Identity Provider Linkage: Connect your chosen Identity Provider (e.g., GitHub, Google) to Keycloak. To facilitate this process, you may use the initialization script available at [Minder Identity Initialization Script](https://github.com/mindersec/minder/blob/main/identity/scripts/initialize.sh). +1. **Realm Configuration:** Set up a dedicated realm in Keycloak for Minder's + use. +2. **Client Setup:** Create two separate clients within the realm: + - **minder-cli:** A client for command-line interactions. + - **minder-server:** A client for server-side operations. +3. Identity Provider Linkage: Connect your chosen Identity Provider (e.g., + GitHub, Google) to Keycloak. To facilitate this process, you may use the + initialization script available at + [Minder Identity Initialization Script](https://github.com/mindersec/minder/blob/main/identity/scripts/initialize.sh). ## Postgres Installation -Minder requires a dedicated Postgres database to store its operational data. The database must have a dedicated user with the necessary privileges and credentials. + +Minder requires a dedicated Postgres database to store its operational data. The +database must have a dedicated user with the necessary privileges and +credentials. ### Best Practices for Database Deployment + It is recommended to use two distinct database users: - One for the Minder server operations. - Another solely for database migrations. -You can find our database migration scripts at [Minder Database Migrations](https://github.com/mindersec/minder/tree/main/database/migrations). +You can find our database migration scripts at +[Minder Database Migrations](https://github.com/mindersec/minder/tree/main/database/migrations). ## Ingress Configuration -Your ingress controller must be capable of handling both gRPC and HTTP/1 protocols. -Minder exposes both HTTP and gRPC APIs, and our default Helm chart configuration enables ingress for both protocols. If your ingress solution requires different settings, please disable the default ingress in the Helm chart and configure it manually to meet your environment's needs. +Your ingress controller must be capable of handling both gRPC and HTTP/1 +protocols. + +Minder exposes both HTTP and gRPC APIs, and our default Helm chart configuration +enables ingress for both protocols. If your ingress solution requires different +settings, please disable the default ingress in the Helm chart and configure it +manually to meet your environment's needs. ## GitHub OAuth Application -For Minder to interact with GitHub repositories, a GitHub OAuth2 application is required. This is essential for Minder's operation, as it will use this application to authenticate and perform actions on GitHub repositories. -Please ensure the following secrets are securely stored and handled, as they contain sensitive information crucial for the authentication and operation of Minder's integrations: +For Minder to interact with GitHub repositories, a GitHub OAuth2 application is +required. This is essential for Minder's operation, as it will use this +application to authenticate and perform actions on GitHub repositories. + +Please ensure the following secrets are securely stored and handled, as they +contain sensitive information crucial for the authentication and operation of +Minder's integrations: -- **minder-identity-secrets:** a secret with the key identity_client_secret and the value being the keycloak minder-server client secret. -- **minder-auth-secrets:** a secret with the key token_key_passphrase and unique content, used to encrypt tokens in the database. -- **minder-github-secrets:** a secret with the keys client_id and client_secret that contains the GitHub OAuth app secrets. +- **minder-identity-secrets:** a secret with the key identity_client_secret and + the value being the keycloak minder-server client secret. +- **minder-auth-secrets:** a secret with the key token_key_passphrase and unique + content, used to encrypt tokens in the database. +- **minder-github-secrets:** a secret with the keys client_id and client_secret + that contains the GitHub OAuth app secrets. ## Helm Chart Parameters + ### Minder -![Version: 0.1.0](https://img.shields.io/badge/Version-0.1.0-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: 2023-07-31](https://img.shields.io/badge/AppVersion-2023--07--31-informational?style=flat-square) +![Version: 0.1.0](https://img.shields.io/badge/Version-0.1.0-informational?style=flat-square) +![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) +![AppVersion: 2023-07-31](https://img.shields.io/badge/AppVersion-2023--07--31-informational?style=flat-square) Deploy Minder on Kubernetes ### Requirements -| Repository | Name | Version | -|------------|------|---------| -| oci://registry-1.docker.io/bitnamicharts | common | 2.x.x | +| Repository | Name | Version | +| ---------------------------------------- | ------ | ------- | +| oci://registry-1.docker.io/bitnamicharts | common | 2.x.x | ### Values -| Key | Type | Default | Description | -|-----|------|---------|-------------| -| aws.accountID | string | `"123456789012"` | AWS account ID where the service will be deployed | -| aws.migrate.iamRole | string | `"minder_migrate_role"` | IAM role for the migration operations in AWS | -| aws.server.iamRole | string | `"minder_server_role"` | IAM role for the server operations in AWS | -| db.host | string | `"postgres.postgres"` | Hostname for the database where Minder will store its data | -| deploymentSettings.extraVolumeMounts | string | `nil` | Additional volume mounts for the deployment | -| deploymentSettings.extraVolumes | string | `nil` | Additional volumes to mount into the deployment | -| deploymentSettings.image | string | `"ko://github.com/mindersec/minder/cmd/server"` | Image to use for the main Minder deployment | -| deploymentSettings.imagePullPolicy | string | `"IfNotPresent"` | Image pull policy for the main deployment | -| deploymentSettings.resources | object | `{"limits":{"cpu":4,"memory":"1.5Gi"},"requests":{"cpu":1,"memory":"1Gi"}}` | Compute resource requests and limits for the main deployment | -| deploymentSettings.secrets | object | `{"appSecretName":"minder-github-secrets","authSecretName":"minder-auth-secrets","identitySecretName":"minder-identity-secrets"}` | Names of the secrets for various Minder components | -| hostname | string | `"minder.example.com"` | The hostname for the Minder service | -| hpaSettings.maxReplicas | int | `1` | Maximum number of replicas for HPA | -| hpaSettings.metrics | object | `{"cpu":{"targetAverageUtilization":60}}` | Target CPU utilization percentage for HPA to scale | -| hpaSettings.minReplicas | int | `1` | Minimum number of replicas for HPA | -| ingress.annotations | object | `{}` | Ingress annotations | -| migrationSettings.image | string | `"ko://github.com/mindersec/minder/cmd/server"` | Image to use for the migration jobs | -| migrationSettings.imagePullPolicy | string | `"IfNotPresent"` | Image pull policy for the migration jobs | -| migrationSettings.resources | object | `{"limits":{"cpu":1,"memory":"300Mi"},"requests":{"cpu":"200m","memory":"200Mi"}}` | Compute resource requests and limits for the migration jobs | -| service.grpcPort | int | `8090` | GRPC port for the service to listen on | -| service.httpPort | int | `8080` | HTTP port for the service to listen on | -| service.metricPort | int | `9090` | Metrics port for the service to expose metrics on | -| serviceAccounts.migrate | string | `""` | ServiceAccount to be used for migration. If set, Minder will use this named ServiceAccount. | -| serviceAccounts.server | string | `""` | ServiceAccount to be used by the server. If set, Minder will use this named ServiceAccount. | -| trusty.endpoint | string | `"https://api.trustypkg.dev"` | Endpoint for the Stacklok Insight service which Minder communicates with | +| Key | Type | Default | Description | +| ------------------------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | +| aws.accountID | string | `"123456789012"` | AWS account ID where the service will be deployed | +| aws.migrate.iamRole | string | `"minder_migrate_role"` | IAM role for the migration operations in AWS | +| aws.server.iamRole | string | `"minder_server_role"` | IAM role for the server operations in AWS | +| db.host | string | `"postgres.postgres"` | Hostname for the database where Minder will store its data | +| deploymentSettings.extraVolumeMounts | string | `nil` | Additional volume mounts for the deployment | +| deploymentSettings.extraVolumes | string | `nil` | Additional volumes to mount into the deployment | +| deploymentSettings.image | string | `"ko://github.com/mindersec/minder/cmd/server"` | Image to use for the main Minder deployment | +| deploymentSettings.imagePullPolicy | string | `"IfNotPresent"` | Image pull policy for the main deployment | +| deploymentSettings.resources | object | `{"limits":{"cpu":4,"memory":"1.5Gi"},"requests":{"cpu":1,"memory":"1Gi"}}` | Compute resource requests and limits for the main deployment | +| deploymentSettings.secrets | object | `{"appSecretName":"minder-github-secrets","authSecretName":"minder-auth-secrets","identitySecretName":"minder-identity-secrets"}` | Names of the secrets for various Minder components | +| hostname | string | `"minder.example.com"` | The hostname for the Minder service | +| hpaSettings.maxReplicas | int | `1` | Maximum number of replicas for HPA | +| hpaSettings.metrics | object | `{"cpu":{"targetAverageUtilization":60}}` | Target CPU utilization percentage for HPA to scale | +| hpaSettings.minReplicas | int | `1` | Minimum number of replicas for HPA | +| ingress.annotations | object | `{}` | Ingress annotations | +| migrationSettings.image | string | `"ko://github.com/mindersec/minder/cmd/server"` | Image to use for the migration jobs | +| migrationSettings.imagePullPolicy | string | `"IfNotPresent"` | Image pull policy for the migration jobs | +| migrationSettings.resources | object | `{"limits":{"cpu":1,"memory":"300Mi"},"requests":{"cpu":"200m","memory":"200Mi"}}` | Compute resource requests and limits for the migration jobs | +| service.grpcPort | int | `8090` | GRPC port for the service to listen on | +| service.httpPort | int | `8080` | HTTP port for the service to listen on | +| service.metricPort | int | `9090` | Metrics port for the service to expose metrics on | +| serviceAccounts.migrate | string | `""` | ServiceAccount to be used for migration. If set, Minder will use this named ServiceAccount. | +| serviceAccounts.server | string | `""` | ServiceAccount to be used by the server. If set, Minder will use this named ServiceAccount. | +| trusty.endpoint | string | `"https://api.trustypkg.dev"` | Endpoint for the Stacklok Insight service which Minder communicates with | diff --git a/docs/docs/run_minder_server/intro_to_install.md b/docs/docs/run_minder_server/intro_to_install.md index 6f7128c14a..6e04c8dddd 100644 --- a/docs/docs/run_minder_server/intro_to_install.md +++ b/docs/docs/run_minder_server/intro_to_install.md @@ -5,7 +5,8 @@ sidebar_position: 5 # Introduction to running Minder -Minder is platform, comprising of a control plane, a CLI, a database and an identity provider. +Minder is platform, comprising of a control plane, a CLI, a database and an +identity provider. The control plane runs two endpoints, a gRPC endpoint and a HTTP endpoint. @@ -15,7 +16,14 @@ PostgreSQL is used as the database. Keycloak is used as the identity provider. -Depending on your goal, there are two methods to get started running a Minder server -- If you are interested in contributing to Minder as a developer, you can build Minder from source, while deploying its dependencies via containers. Follow the [Installing a Development version](./run_the_server.md) instructions. +Depending on your goal, there are two methods to get started running a Minder +server -- If you'd like to run Minder as an end user or a production application, you should install using Helm. This method requires you to provide and configure your own identity provider and database. Follow the [Installing a Production version](./installing_minder.md) instructions. +- If you are interested in contributing to Minder as a developer, you can build + Minder from source, while deploying its dependencies via containers. Follow + the [Installing a Development version](./run_the_server.md) instructions. + +- If you'd like to run Minder as an end user or a production application, you + should install using Helm. This method requires you to provide and configure + your own identity provider and database. Follow the + [Installing a Production version](./installing_minder.md) instructions. diff --git a/docs/docs/run_minder_server/run_the_server.md b/docs/docs/run_minder_server/run_the_server.md index edcb8f4f20..641d3f2c53 100644 --- a/docs/docs/run_minder_server/run_the_server.md +++ b/docs/docs/run_minder_server/run_the_server.md @@ -3,17 +3,20 @@ title: Installing a Development version sidebar_position: 10 --- -# Installing a Development version +# Installing a Development version + +This guide shows you how to run a Minder server locally. It is intended for +users who would like to contribute to the Minder project. It is not intended for +production use. This guide will walk you through how to: -This guide shows you how to run a Minder server locally. It is intended for users who would like to contribute to the Minder project. It is not intended for production use. -This guide will walk you through how to: - Retrieve the latest source code - Set up your development environment - Run the dependent applications - Create a Provider - Set up authentication -Once you complete this guide, you will have a Minder server built from source and ready to contribute to. +Once you complete this guide, you will have a Minder server built from source +and ready to contribute to. ## Prerequisites @@ -23,11 +26,11 @@ Once you complete this guide, you will have a Minder server built from source an - [ko](https://ko.build/install/) - [yq](https://github.com/mikefarah/yq) - ## Steps ### Clone the repository -Begin by cloning the Minder repository to get the latest source code. + +Begin by cloning the Minder repository to get the latest source code. ```bash git clone git@github.com:mindersec/minder.git @@ -35,70 +38,95 @@ cd minder ``` ### Set up Development Environment + To set up your development environment, run: ```bash make bootstrap ``` -This will install the required tools for running different make targets, initialize required configuration files, as well as generate a token key passphrase. + +This will install the required tools for running different make targets, +initialize required configuration files, as well as generate a token key +passphrase. ### Build the application -Run the following to build minder and minder-server (binaries will be present at ./bin/) + +Run the following to build minder and minder-server (binaries will be present at +./bin/) + ```bash make build ``` -You may copy these into a location on your path, or run them directly from the `bin` directory. - +You may copy these into a location on your path, or run them directly from the +`bin` directory. ### Configure the Repository Provider -You now need to create a Provider to enable Minder to inspect and manage your repository configuration. Currently only GitHub is supported as a Provider, so we'll do this using a GitHub App. This app will also provide Keycloak with an authentication source. Follow the steps in [Configuring a Provider](./config_provider.md) then return here to complete configuring the server. Be sure to save the Client ID and Client secret values, because you will need them again below. +You now need to create a Provider to enable Minder to inspect and manage your +repository configuration. Currently only GitHub is supported as a Provider, so +we'll do this using a GitHub App. This app will also provide Keycloak with an +authentication source. Follow the steps in +[Configuring a Provider](./config_provider.md) then return here to complete +configuring the server. Be sure to save the Client ID and Client secret values, +because you will need them again below. ### Start the Minder server -At this point, you should have a GitHub provider configured and your `server-config.yaml` file updated. -Start `minder-server` along with its dependent services (`keycloak` and `postgres`) by running: + +At this point, you should have a GitHub provider configured and your +`server-config.yaml` file updated. Start `minder-server` along with its +dependent services (`keycloak` and `postgres`) by running: ```bash make run-docker ``` -As this command runs, you will see it build the Minder server container and then start the dependent containers. -If you run + +As this command runs, you will see it build the Minder server container and then +start the dependent containers. If you run + ```bash docker ps ``` + you should see 4 new services running: + - keycloak - minder - openfga - postgres -At this point, you might also want to ensure that created folders are owned by the current user - e.g.: +At this point, you might also want to ensure that created folders are owned by +the current user - e.g.: + ```bash sudo chown "$(id -un):$(id -gn)" {flags-config.yaml,.secrets,.ssh} ``` - ### Configure Keycloak -Now that the Keycloak application is running, you need to configure it using the GitHub App you previously configured. -To enable GitHub login on Keycloak run the following command, using the `client_id` and `client_secret` you generated setting up the GitHub app: + +Now that the Keycloak application is running, you need to configure it using the +GitHub App you previously configured. To enable GitHub login on Keycloak run the +following command, using the `client_id` and `client_secret` you generated +setting up the GitHub app: ```bash make KC_GITHUB_CLIENT_ID= KC_GITHUB_CLIENT_SECRET= github-login ``` -You should see it create a new instance and new mappers. You may see a resource not found message. This is safe to ignore. +You should see it create a new instance and new mappers. You may see a resource +not found message. This is safe to ignore. +### Authenticate minder -### Authenticate minder At this point, you should have the following: - A PostgreSQL database and Keycloak and OpenFGA instances running in containers -- A minder-server built from source running in a container +- A minder-server built from source running in a container - A GitHub application configured to provide access to a set of repositories -The final step is to authenticate the `minder` application using Keycloak and the GitHub application that was previous configured. -To do this run: +The final step is to authenticate the `minder` application using Keycloak and +the GitHub application that was previous configured. To do this run: + ```bash minder auth login ``` @@ -107,45 +135,61 @@ This will open Keycloak login window in your browser. ![Keycloak Login](./images/keycloak-login.png) -Click GitHub to sign in. This should display a GitHub authorization window asking if you'd like to give permission to your Minder server. +Click GitHub to sign in. This should display a GitHub authorization window +asking if you'd like to give permission to your Minder server. ![Github Auth](./images/github-auth.png) -Click Authorize. The browser window should say Authentication Successful and the command line should say you've been successfully registered. +Click Authorize. The browser window should say Authentication Successful and the +command line should say you've been successfully registered. ![Successful Minder Auth](./images/successful-install.png) +Congratulations! You've set up a Minder server! Now you're all ready to +contribute to Minder. -Congratulations! You've set up a Minder server! Now you're all ready to contribute to Minder. - -For more information about the development process, please see the [Developer Guide](https://minder-docs.stacklok.dev/developer_guide/get-hacking). +For more information about the development process, please see the +[Developer Guide](https://minder-docs.stacklok.dev/developer_guide/get-hacking). -For more information on contributing, please see our [Contributing Guide](https://github.com/mindersec/minder/blob/main/CONTRIBUTING.md). - -A list of good first issues can be found in the [Minder GitHub project](https://github.com/mindersec/minder/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22). +For more information on contributing, please see our +[Contributing Guide](https://github.com/mindersec/minder/blob/main/CONTRIBUTING.md). +A list of good first issues can be found in the +[Minder GitHub project](https://github.com/mindersec/minder/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22). ## Optional Steps ### Setting up a Webhook -With the basic setup, GitHub is unable to notify Minder when certain events occur in your repositories. MORE DETAILS WOULD BE NICE. Configuring a Webhook will allow GitHub to communicate back to the Minder instance. Details on how to set this up can be found in the [Configuring a Webhook](./config_webhook.md) guide. + +With the basic setup, GitHub is unable to notify Minder when certain events +occur in your repositories. MORE DETAILS WOULD BE NICE. Configuring a Webhook +will allow GitHub to communicate back to the Minder instance. Details on how to +set this up can be found in the [Configuring a Webhook](./config_webhook.md) +guide. ### Running Minder server directly -There are certain situations where you might want to run the Minder server directly, instead of as a container. -These steps will allow you to do that. They assume you have completed the basic setup. + +There are certain situations where you might want to run the Minder server +directly, instead of as a container. These steps will allow you to do that. They +assume you have completed the basic setup. #### Stop the Minder server container -Stop the Minder server, while leaving the dependant containers to continue running. + +Stop the Minder server, while leaving the dependant containers to continue +running. + ```bash docker stop minder_server ``` #### Configuration Changes -Find the authz section in your `server-config.yaml` file located in your root Minder directory. Update the `api_url` to point to `http://localhost:8082`. + +Find the authz section in your `server-config.yaml` file located in your root +Minder directory. Update the `api_url` to point to `http://localhost:8082`. ```yaml authz: - api_url: http://localhost:8082 + api_url: http://localhost:8082 store_name: minder auth: # Set to token for production @@ -153,8 +197,12 @@ authz: ``` #### Run the server + Start the server from the command line using the following command: + ```bash go run cmd/server/main.go serve ``` -You should see the server start up and then a series of log messages. You are now running the Minder server directly. + +You should see the server start up and then a series of log messages. You are +now running the Minder server directly. diff --git a/docs/docs/understand/alerts.md b/docs/docs/understand/alerts.md index 6ae6ad7a5c..9cc267131a 100644 --- a/docs/docs/understand/alerts.md +++ b/docs/docs/understand/alerts.md @@ -5,30 +5,40 @@ sidebar_position: 60 # Alerts from Minder -Minder issues _alerts_ to notify you when the state of your software supply chain does not meet the criteria that you've defined in your [profile](profiles.md). +Minder issues _alerts_ to notify you when the state of your software supply +chain does not meet the criteria that you've defined in your +[profile](profiles.md). -Alerts are a core feature of Minder providing you with notifications about the status of your registered -repositories. These alerts automatically open and close based on the evaluation of the rules defined in your profiles. +Alerts are a core feature of Minder providing you with notifications about the +status of your registered repositories. These alerts automatically open and +close based on the evaluation of the rules defined in your profiles. -When a rule fails, Minder opens an alert to bring your attention to the non-compliance issue. Conversely, when the -rule evaluation passes, Minder will automatically close any previously opened alerts related to that rule. +When a rule fails, Minder opens an alert to bring your attention to the +non-compliance issue. Conversely, when the rule evaluation passes, Minder will +automatically close any previously opened alerts related to that rule. In the alert, you'll be able to see details such as: -* The repository that is affected -* The rule type that failed -* The profile that the rule belongs to -* Guidance on how to remediate and also fix the issue -* Severity of the issue. The severity of the alert is based on what is set in the rule type definition. + +- The repository that is affected +- The rule type that failed +- The profile that the rule belongs to +- Guidance on how to remediate and also fix the issue +- Severity of the issue. The severity of the alert is based on what is set in + the rule type definition. ### Enabling alerts in a profile -To activate the alert feature within a profile, you need to adjust the YAML definition. -Specifically, you should set the alert parameter to "on": + +To activate the alert feature within a profile, you need to adjust the YAML +definition. Specifically, you should set the alert parameter to "on": + ```yaml -alert: "on" +alert: 'on' ``` -Enabling alerts at the profile level means that for any rules included in the profile, alerts will be generated for -any rule failures. For better clarity, consider this rule snippet: +Enabling alerts at the profile level means that for any rules included in the +profile, alerts will be generated for any rule failures. For better clarity, +consider this rule snippet: + ```yaml --- version: v1 @@ -36,54 +46,58 @@ type: rule-type name: sample_rule def: alert: - type: security_advisory - security_advisory: - severity: "medium" + type: security_advisory + security_advisory: + severity: 'medium' ``` -In this example, the `sample_rule` defines an alert action that creates a medium severity security advisory in the -repository for any non-compliant repositories. -Now, let's see how this works in practice within a profile. Consider the following profile configuration with alerts -turned on: +In this example, the `sample_rule` defines an alert action that creates a medium +severity security advisory in the repository for any non-compliant repositories. + +Now, let's see how this works in practice within a profile. Consider the +following profile configuration with alerts turned on: + ```yaml version: v1 type: profile name: sample-profile context: provider: github -alert: "on" +alert: 'on' repository: - type: sample_rule def: enabled: true ``` -In this profile, all repositories that do not meet the conditions specified in the `sample_rule` will automatically -generate security advisories. + +In this profile, all repositories that do not meet the conditions specified in +the `sample_rule` will automatically generate security advisories. ## Alert types Minder supports alerts of type GitHub Security Advisory. -The following is an example of how the alert definition looks like for a give rule type: +The following is an example of how the alert definition looks like for a give +rule type: ```yaml --- version: v1 type: rule-type name: artifact_signature -... +--- def: # Defines the configuration for alerting on the rule alert: type: security_advisory security_advisory: - severity: "medium" + severity: 'medium' ``` ## Configuring alerts in profiles -Alerts are configured in the `alert` section of the profile yaml file. The following example shows how to configure -alerts for a profile: +Alerts are configured in the `alert` section of the profile yaml file. The +following example shows how to configure alerts for a profile: ```yaml --- @@ -92,13 +106,14 @@ type: profile name: github-profile context: provider: github -alert: "on" +alert: 'on' repository: - type: secret_scanning def: enabled: true ``` -The `alert` section can be configured with the following values: `on` (default), `off` and `dry_run`. Dry run would be -useful for testing. In `dry_run` Minder will process the alert conditions and output the resulted REST call, but it +The `alert` section can be configured with the following values: `on` (default), +`off` and `dry_run`. Dry run would be useful for testing. In `dry_run` Minder +will process the alert conditions and output the resulted REST call, but it won't execute it. diff --git a/docs/docs/understand/key_concepts.md b/docs/docs/understand/key_concepts.md index 6f29a15be7..24d7be179c 100644 --- a/docs/docs/understand/key_concepts.md +++ b/docs/docs/understand/key_concepts.md @@ -2,146 +2,208 @@ title: Key Concepts sidebar_position: 05 --- -# Key Concepts -Minder implements a platform for enforcing supply chain security policy in a _continuous_ and _automated_ manner. -In addition to policy checks, Minder also supports defining _remediation_ actions that can be automatically executed to assist teams in following the defined policies. -This section introduces the key concepts in Minder for defining _what_ policies should be applied to _which_ resources, and how Minder uses these concepts to enforce security policies. +Minder implements a platform for enforcing supply chain security policy in a +_continuous_ and _automated_ manner. In addition to policy checks, Minder also +supports defining _remediation_ actions that can be automatically executed to +assist teams in following the defined policies. This section introduces the key +concepts in Minder for defining _what_ policies should be applied to _which_ +resources, and how Minder uses these concepts to enforce security policies. -## Managing Supply Chains with Minder +## Managing supply chains with Minder ### Projects -Projects are the unit of tenancy (separation and control of resources by different users) in Minder. -Projects are used to group supply chain components which are managed by a common team, and to apply policies to those components. -One user may be a member of multiple projects, and one project may be managed by multiple users. +Projects are the unit of tenancy (separation and control of resources by +different users) in Minder. Projects are used to group supply chain components +which are managed by a common team, and to apply policies to those components. +One user may be a member of multiple projects, and one project may be managed by +multiple users. -Users can be assigned a [role](../user_management/user_roles.md) in a project, which determines their permissions to view and manage the project's resources, such as [entities](#entities), [providers](#providers), and [profiles](#profiles). +Users can be assigned a [role](../user_management/user_roles.md) in a project, +which determines their permissions to view and manage the project's resources, +such as [entities](#entities), [providers](#providers), and +[profiles](#profiles). ### Entities -Entities represent components in the supply chain, such as repositories, pull requests, or artifacts. -Minder uses entities to track which supply chain components are associated with which policies and rules, which guides [rule evaluation](#rule-evaluation) when it occurs. -In addition to an intrinsic identifier (such as github repo name), entities have a set of system-provided _properties_ which are extracted from the underlying system and can be used when evaluating policies. +Entities represent components in the supply chain, such as repositories, pull +requests, or artifacts. Minder uses entities to track which supply chain +components are associated with which policies and rules, which guides +[rule evaluation](#phases-of-evaluation) when it occurs. In addition to an +intrinsic identifier (such as GitHub repo name), entities have a set of +system-provided _properties_ which are extracted from the underlying system and +can be used when evaluating policies. Entities are created and managed by providers. ### Providers -Providers are Minder’s integration points with external systems, such as GitHub or the Docker registry. -Providers track the credentials and permissions needed to interact with these services, and enable both manual and automatic creation of entities, depending on the entity type and provider configuration. -In general, references to an entity need to be _qualified_ by the context of the provider that created the entity, though the Minder API will attempt to deduce the appropriate provider where possible. +Providers are Minder’s integration points with external systems, such as GitHub +or the Docker registry. Providers track the credentials and permissions needed +to interact with these services, and enable both manual and automatic creation +of entities, depending on the entity type and provider configuration. In +general, references to an entity need to be _qualified_ by the context of the +provider that created the entity, though the Minder API will attempt to deduce +the appropriate provider where possible. Examples: -* GitHub and GitLab: Track repositories, pull requests, and CI/CD pipelines. +- GitHub and GitLab: Track repositories, pull requests, and CI/CD pipelines. -* Docker Hub: Monitor container images and their metadata. +- Docker Hub: Monitor container images and their metadata. -Providers communicate with Minder through APIs, webhook events, and scheduled updates. This ensures -continuous monitoring and up-to-date information about the entities they manage. +Providers communicate with Minder through APIs, webhook events, and scheduled +updates. This ensures continuous monitoring and up-to-date information about the +entities they manage. #### Origination -Some entities are automatically created by a provider due to existing relationships in the external system that the provider interacts with. -Origination is the term used to describe entities which have been automatically created due to their relationship with an existing entity. -For instance, a pull request originates from a repository. +Some entities are automatically created by a provider due to existing +relationships in the external system that the provider interacts with. +Origination is the term used to describe entities which have been automatically +created due to their relationship with an existing entity. For instance, a pull +request originates from a repository. This concept ensures that Minder maintains lifecycle consistency by: -* Automatically creating derived entities (e.g., pull requests) based on originating ones. +- Automatically creating derived entities (e.g., pull requests) based on + originating ones. -* Deleting dependent entities when the originating entity is removed. +- Deleting dependent entities when the originating entity is removed. Example Relationships: - Repository -> Pull Request +- Repository -> Pull Request - Repository -> Release +- Repository -> Release ### Profiles -Profiles represent a collection of individual controls or policies which collectively enforce a security posture or other requirements on a set of entities. -Profiles contain a collection of [rule types](#rule-types) with parameters (such as permitted CVE severity or allowed license types) to control the execution of the rule. -Best practice is to define profiles that apply a set of related behaviors, and define your desired security posture via the application of multiple profiles. - -Profiles are specific to each project, but can apply to entities across multiple providers with the project. -While profiles apply to all entities in a project by default, profiles may contain a [selector](../how-to/profile_selectors.md) which limits to the profile to only entities matched by the selector expression. - -#### Rule Types - -Rule types define individual checks for specific aspects of an entity, such as ensuring secret scanning is enabled or that artifacts are signed. -While a rule type defines a specific check on an entity, rule types may also contain parameters which can be set by the profile which applies the rule type to the selected set of entities. -In this way, a single rule type (for example, requiring GitHub Actions configuration) can be parameterized for different programming languages, licenses, or repository visibility. - -Like profiles, rule types are specific to a project, but the same definition can be shared and loaded into multiple projects. -A collection of useful rule definitions is available in https://github.com/mindersec/minder-rules-and-profiles. - -## Executing Policy With Minder - -### Phases of Evaluation - -Minder attempts to ensure that entities are continuously against the defined polices. -It does this by performing rule evaluation at various times, including when entities are first registered, when notified of a change to an entity, and (soon) periodically to catch changes which are not notified. -When executing the rules from a policy, Minder proceedes to evaluate all the rules in the relevant policies in parallel using the following phases: +Profiles represent a collection of individual controls or policies which +collectively enforce a security posture or other requirements on a set of +entities. Profiles contain a collection of [rule types](#rule-types) with +parameters (such as permitted CVE severity or allowed license types) to control +the execution of the rule. Best practice is to define profiles that apply a set +of related behaviors, and define your desired security posture via the +application of multiple profiles. + +Profiles are specific to each project, but can apply to entities across multiple +providers with the project. While profiles apply to all entities in a project by +default, profiles may contain a [selector](../how-to/profile_selectors.md) which +limits to the profile to only entities matched by the selector expression. + +#### Rule types + +Rule types define individual checks for specific aspects of an entity, such as +ensuring secret scanning is enabled or that artifacts are signed. While a rule +type defines a specific check on an entity, rule types may also contain +parameters which can be set by the profile which applies the rule type to the +selected set of entities. In this way, a single rule type (for example, +requiring GitHub Actions configuration) can be parameterized for different +programming languages, licenses, or repository visibility. + +Like profiles, rule types are specific to a project, but the same definition can +be shared and loaded into multiple projects. A collection of useful rule +definitions is available in +https://github.com/mindersec/minder-rules-and-profiles. + +## Executing policy with Minder + +### Phases of evaluation + +Minder attempts to ensure that entities are continuously against the defined +polices. It does this by performing rule evaluation at various times, including +when entities are first registered, when notified of a change to an entity, and +(soon) periodically to catch changes which are not notified. When executing the +rules from a policy, Minder proceeds to evaluate all the rules in the relevant +policies in parallel using the following phases: 1. **Ingestion**: Fetch the latest state of the entity from the provider. 2. **Evaluation**: Evaluate the rules against the entity. 3. **Remediation**: If a rule fails, attempt to remediate the entity. 4. **Alert**: If a rule fails and remediation is not possible, create an alert. -The details of rule evaluation are covered [in a separate document](./rule_evaluation.md); this section provides a high level overview to complement the policy management constructs described in [managing supply chains](#managing-supply-chains-with-minder). +The details of rule evaluation are covered +[in a separate document](./rule_evaluation.md); this section provides a high +level overview to complement the policy management constructs described in +[managing supply chains](#managing-supply-chains-with-minder). ### Ingesters -Ingesters fetch data about the entity using provider-specific code. -Depending on the type of entity, this data might include results from API calls, file contents, or other data such as attestations. -Generally, data from the ingestion phase will be made available as either structured data (such as a JSON document) or through Rego functions in the Rego evaluation engine. - -### Evaluation Engines - -The rule evaluation engine is at the heart of defining policies on supply chain entities. -It allows rule type authors to compare the data fetched during the ingestion stage with expected values, and determine whether the entity meets the policy requirements. - -Minder currently supports two rule evaluation engines: `rego` and `jq`. -The `jq` engine is useful for evaluating simple expressions against constant or parameterized values, while the `rego` engine is more powerful, and allows writing expressions with conditionals, loops and dynamic data fetching. - -At the end of the rule evaluation, each rule type yields a result, which can be one of four values: -* `pass`: The entity meets the policy requirements. -* `fail`: The entity does not meet the policy requirements. -* `skip`: The rule was skipped because it did not apply to the entity. -* `error`: An error occurred during the evaluation. - -#### Data Sources - -Data sources complement providers by fetching additional contextual information from -third-party APIs. -Data sources are currently only available in the Rego evaluation engine. -While providers manage entities and can supply data during the ingestion phase, data sources provide a structured interface to data sources which can be queried dynamically by the rule engine.. - -Like rule types and profiles, data sources are defined in the context of a project. -Data types generally fetch data from an external network service, and can be used to enrich the data extracted by the rule engine: - -* A data source might query the Open Source Vulnerabilities (OSV) database to check -for known vulnerabilities in dependencies listed in a repository’s manifest file. - -* A data source might query an external service to check for the correctness and availability -of release assets. - -* A data source might be used to fetch additional information from the same API as the provider to compare data from two different sources, such as the list of branches and the branch protection rules. - -#### Remediations and Alerts - -For rule types which produce a `fail` result for an entity, remediations and alerts define corrective actions which Minder can take to restore the entity to a policy-compliant state. -Remediations and alerts may each be defined as part of the rule type; some rule may define only a remediation, only an alert, both, or neither. - -Generally, remediations define actions which Minder can take which will directly address the identified issue -- for example, updating an entity via a REST API or proposing a change through a pull request. -Alerts provide a mechanism for providing feedback to humans about the non-compliant state of an entity; while alerts may provide detailed advice on how to correct a problem, they do not correct the problem on their own. - -While rule types define the remediation and alert mechanisms, policies can enable or disable the execution of either remediations or alerts. -This allows policy authors to begin implementing rules by measuing policy compliance before adding remediation or alert actions which may disrupt the workflow of developers. - -#### Historical Evaluation Records - -In addition to remediation and alert actions, Minder also maintains a historical evaluation record for each rule. -This record includes information about when the rule was evaluated, the evaluation result, and any messages and actions taken as a result of the rule evaluation. \ No newline at end of file +Ingesters fetch data about the entity using provider-specific code. Depending on +the type of entity, this data might include results from API calls, file +contents, or other data such as attestations. Generally, data from the ingestion +phase will be made available as either structured data (such as a JSON document) +or through Rego functions in the Rego evaluation engine. + +### Evaluation engines + +The rule evaluation engine is at the heart of defining policies on supply chain +entities. It allows rule type authors to compare the data fetched during the +ingestion stage with expected values, and determine whether the entity meets the +policy requirements. + +Minder currently supports two rule evaluation engines: `rego` and `jq`. The `jq` +engine is useful for evaluating simple expressions against constant or +parameterized values, while the `rego` engine is more powerful, and allows +writing expressions with conditionals, loops and dynamic data fetching. + +At the end of the rule evaluation, each rule type yields a result, which can be +one of four values: + +- `pass`: The entity meets the policy requirements. +- `fail`: The entity does not meet the policy requirements. +- `skip`: The rule was skipped because it did not apply to the entity. +- `error`: An error occurred during the evaluation. + +#### Data sources + +Data sources complement providers by fetching additional contextual information +from third-party APIs. Data sources are currently only available in the Rego +evaluation engine. While providers manage entities and can supply data during +the ingestion phase, data sources provide a structured interface to data sources +which can be queried dynamically by the rule engine.. + +Like rule types and profiles, data sources are defined in the context of a +project. Data types generally fetch data from an external network service, and +can be used to enrich the data extracted by the rule engine: + +- A data source might query the Open Source Vulnerabilities (OSV) database to + check for known vulnerabilities in dependencies listed in a repository’s + manifest file. + +- A data source might query an external service to check for the correctness and + availability of release assets. + +- A data source might be used to fetch additional information from the same API + as the provider to compare data from two different sources, such as the list + of branches and the branch protection rules. + +#### Remediations and alerts + +For rule types which produce a `fail` result for an entity, remediations and +alerts define corrective actions which Minder can take to restore the entity to +a policy-compliant state. Remediations and alerts may each be defined as part of +the rule type; some rule may define only a remediation, only an alert, both, or +neither. + +Generally, remediations define actions which Minder can take which will directly +address the identified issue -- for example, updating an entity via a REST API +or proposing a change through a pull request. Alerts provide a mechanism for +providing feedback to humans about the non-compliant state of an entity; while +alerts may provide detailed advice on how to correct a problem, they do not +correct the problem on their own. + +While rule types define the remediation and alert mechanisms, policies can +enable or disable the execution of either remediations or alerts. This allows +policy authors to begin implementing rules by measuring policy compliance before +adding remediation or alert actions which may disrupt the workflow of +developers. + +#### Historical evaluation records + +In addition to remediation and alert actions, Minder also maintains a historical +evaluation record for each rule. This record includes information about when the +rule was evaluated, the evaluation result, and any messages and actions taken as +a result of the rule evaluation. diff --git a/docs/docs/understand/profiles.md b/docs/docs/understand/profiles.md index 0e710dd798..191f07dea2 100644 --- a/docs/docs/understand/profiles.md +++ b/docs/docs/understand/profiles.md @@ -5,35 +5,49 @@ sidebar_position: 10 # Profiles in Minder -A _profile_ defines your security policies that you want to apply to your software supply chain. Profiles contain rules that query data in a [provider](providers.md), and specifies whether Minder will issue [alerts](alerts.md) or perform automatic [remediations](remediations.md) when an entity is not in compliance with the policy. +A _profile_ defines your security policies that you want to apply to your +software supply chain. Profiles contain rules that query data in a +[provider](providers.md), and specifies whether Minder will issue +[alerts](alerts.md) or perform automatic [remediations](remediations.md) when an +entity is not in compliance with the policy. -Profiles in Minder allow you to group and manage -rules for various entity types, such as repositories, pull requests, and artifacts, across your registered GitHub -repositories. +Profiles in Minder allow you to group and manage rules for various entity types, +such as repositories, pull requests, and artifacts, across your registered +GitHub repositories. The anatomy of a profile is the profile itself, which outlines the rules to be -checked, the rule types, and the evaluation engine. Profiles are defined in a YAML file and can be configured to meet your compliance requirements. -As of time of writing, Minder supports the following evaluation engines: +checked, the rule types, and the evaluation engine. Profiles are defined in a +YAML file and can be configured to meet your compliance requirements. As of time +of writing, Minder supports the following evaluation engines: -* **[Rego](https://www.openpolicyagent.org/docs/latest/policy-language/)** Open Policy Agents's native query language, Rego. -* **[JQ](https://jqlang.github.io/jq/)** - a lightweight and flexible command-line JSON processor. +- **[Rego](https://www.openpolicyagent.org/docs/latest/policy-language/)** Open + Policy Agents's native query language, Rego. +- **[JQ](https://jqlang.github.io/jq/)** - a lightweight and flexible + command-line JSON processor. Each engine is designed to be extensible, allowing you to integrate your own logic and processes. -Stacklok has published [a set of example profiles on GitHub](https://github.com/mindersec/minder-rules-and-profiles/tree/main/profiles/github); see [Managing Profiles](../how-to/manage_profiles.md) for more details on how to set up profiles and rule types. +Stacklok has published +[a set of example profiles on GitHub](https://github.com/mindersec/minder-rules-and-profiles/tree/main/profiles/github); +see [Managing Profiles](../how-to/manage_profiles.md) for more details on how to +set up profiles and rule types. ## Rules -Each rule type within a profile is evaluated against your repositories that are registered with Minder. +Each rule type within a profile is evaluated against your repositories that are +registered with Minder. -The available entity rule type groups are `repository`, `pull_request`, and `artifact`. +The available entity rule type groups are `repository`, `pull_request`, and +`artifact`. Each rule type group has a set of rules that can be configured individually. -The available properties for each rule type can be found in their YAML file under the `def.rule_schema.properties` section. +The available properties for each rule type can be found in their YAML file +under the `def.rule_schema.properties` section. -For example, the `secret_scanning` rule type has the following `enabled` property: +For example, the `secret_scanning` rule type has the following `enabled` +property: ```yaml --- @@ -50,27 +64,31 @@ def: default: true ``` -You can find a list of available rules in the [https://github.com/mindersec/minder-rules-and-profiles](https://github.com/mindersec/minder-rules-and-profiles/tree/main/rule-types/github) repository. +You can find a list of available rules in the +[https://github.com/mindersec/minder-rules-and-profiles](https://github.com/mindersec/minder-rules-and-profiles/tree/main/rule-types/github) +repository. ## Actions -Minder supports the ability to perform actions based on the evaluation of a rule such as creating alerts -and automatically remediating non-compliant rules. +Minder supports the ability to perform actions based on the evaluation of a rule +such as creating alerts and automatically remediating non-compliant rules. -When a rule fails, Minder can open an alert to bring your attention to the non-compliance issue. Conversely, when the -rule evaluation passes, Minder will automatically close any previously opened alerts related to that rule. +When a rule fails, Minder can open an alert to bring your attention to the +non-compliance issue. Conversely, when the rule evaluation passes, Minder will +automatically close any previously opened alerts related to that rule. -Minder also supports the ability to automatically remediate failed rules based on their type, i.e., by processing a -REST call to enable/disable a non-compliant repository setting or creating a pull request with a proposed fix. Note -that not all rule types support automatic remediation yet. +Minder also supports the ability to automatically remediate failed rules based +on their type, i.e., by processing a REST call to enable/disable a non-compliant +repository setting or creating a pull request with a proposed fix. Note that not +all rule types support automatic remediation yet. -Both alerts and remediations are configured in the profile YAML file under `alerts` (Default: `on`) -and `remediate` (Default: `off`). +Both alerts and remediations are configured in the profile YAML file under +`alerts` (Default: `on`) and `remediate` (Default: `off`). ## Example profile -Here's a profile which has a single rule for each entity group and its `alert` and `remediate` features are both -turned `on`: +Here's a profile which has a single rule for each entity group and its `alert` +and `remediate` features are both turned `on`: ```yaml --- @@ -79,8 +97,8 @@ type: profile name: github-profile context: provider: github -alert: "on" -remediate: "on" +alert: 'on' +remediate: 'on' repository: - type: dependabot_configured def: diff --git a/docs/docs/understand/providers.md b/docs/docs/understand/providers.md index 11665027a1..cb54c1d25e 100644 --- a/docs/docs/understand/providers.md +++ b/docs/docs/understand/providers.md @@ -5,25 +5,36 @@ sidebar_position: 20 # Providers in Minder -A _provider_ connects Minder to your software supply chain — giving Minder information about your source code repositories, and their pull requests, dependencies, and artifacts. Minder will apply your [profiles](profiles.md) to providers to analyze the security posture of your software supply chain, and then will create [alerts](alerts.md) and can automatically [remediate](remediations.md) problems that it finds. +A _provider_ connects Minder to your software supply chain — giving Minder +information about your source code repositories, and their pull requests, +dependencies, and artifacts. Minder will apply your [profiles](profiles.md) to +providers to analyze the security posture of your software supply chain, and +then will create [alerts](alerts.md) and can automatically +[remediate](remediations.md) problems that it finds. The currently supported providers are: -* GitHub + +- GitHub Stay tuned as we add more providers in the future! ## Enrolling a provider To enroll GitHub as a provider, use the following command: + ``` minder provider enroll ``` -Note: If you are enrolling an organization, the account you use to enroll must be an Owner in the organization -or an Admin on the repositories you will be registering. +Note: If you are enrolling an organization, the account you use to enroll must +be an Owner in the organization or an Admin on the repositories you will be +registering. -Once a provider is enrolled, public repositories from that provider can be registered with Minder. Security profiles -can then be applied to the registered repositories, giving you an overview of your security posture and providing +Once a provider is enrolled, public repositories from that provider can be +registered with Minder. Security profiles can then be applied to the registered +repositories, giving you an overview of your security posture and providing remediations to improve your security posture. -For more information about providers and their configuration, see the [Provider Integrations](../integrations/provider_integrations/github.md) documentation. \ No newline at end of file +For more information about providers and their configuration, see the +[Provider Integrations](../integrations/provider_integrations/github.md) +documentation. diff --git a/docs/docs/understand/remediations.md b/docs/docs/understand/remediations.md index 1b8aaa17e8..751e690e73 100644 --- a/docs/docs/understand/remediations.md +++ b/docs/docs/understand/remediations.md @@ -5,21 +5,31 @@ sidebar_position: 70 # Automatic Remediations in Minder -Minder can perform _automatic remediation_ for many rules in an attempt to resolve problems in your software supply chain, and bring your resources into compliance with your [profile](profiles.md). +Minder can perform _automatic remediation_ for many rules in an attempt to +resolve problems in your software supply chain, and bring your resources into +compliance with your [profile](profiles.md). -The steps to take during automatic remediation are defined within the rule itself and can perform actions like sending a REST call to an endpoint to change configuration, or creating a pull request with a proposed fix. +The steps to take during automatic remediation are defined within the rule +itself and can perform actions like sending a REST call to an endpoint to change +configuration, or creating a pull request with a proposed fix. -For example, if you have a rule in your profile that specifies that Secret Scanning should be enabled, and you have enabled automatic remediation in your profile, then Minder will attempt to turn Secret Scanning on in any repositories where it is not enabled. +For example, if you have a rule in your profile that specifies that Secret +Scanning should be enabled, and you have enabled automatic remediation in your +profile, then Minder will attempt to turn Secret Scanning on in any repositories +where it is not enabled. ### Enabling remediations in a profile -To activate the remediation feature within a profile, you need to adjust the YAML definition. -Specifically, you should set the remediate parameter to "on": + +To activate the remediation feature within a profile, you need to adjust the +YAML definition. Specifically, you should set the remediate parameter to "on": + ```yaml -remediate: "on" +remediate: 'on' ``` -Enabling remediation at the profile level means that for any rules included in the profile, a remediation action will be -taken for any rule failures. +Enabling remediation at the profile level means that for any rules included in +the profile, a remediation action will be taken for any rule failures. + ```yaml --- version: v1 @@ -30,33 +40,41 @@ def: type: rest rest: method: PATCH - endpoint: "/repos/{{.Entity.Owner}}/{{.Entity.Name}}" + endpoint: '/repos/{{.Entity.Owner}}/{{.Entity.Name}}' body: | { "security_and_analysis": {"secret_scanning": { "status": "enabled" } } } ``` -In this example, the `sample_rule` defines a remediation action that performs a PATCH request to an endpoint. This -request will modify the state of the repository ensuring it complies with the rule. -Now, let's see how this works in practice within a profile. Consider the following profile configuration with -remediation turned on: +In this example, the `sample_rule` defines a remediation action that performs a +PATCH request to an endpoint. This request will modify the state of the +repository ensuring it complies with the rule. + +Now, let's see how this works in practice within a profile. Consider the +following profile configuration with remediation turned on: + ```yaml version: v1 type: profile name: sample-profile context: provider: github -remediate: "on" +remediate: 'on' repository: - type: sample_rule def: enabled: true ``` -In this profile, all repositories that do not meet the conditions specified in the `sample_rule` will automatically -receive a PATCH request to the specified endpoint. This action will make the repository compliant. + +In this profile, all repositories that do not meet the conditions specified in +the `sample_rule` will automatically receive a PATCH request to the specified +endpoint. This action will make the repository compliant. ## Limitations -Some rule types do not support automatic remediations, due to platform limitations. For example, it may be possible to query the status of a repository configuration, but there may not be an API to _change_ the configuration. In such case, a rule type could detect problems but would not be able to remediate. +Some rule types do not support automatic remediations, due to platform +limitations. For example, it may be possible to query the status of a repository +configuration, but there may not be an API to _change_ the configuration. In +such case, a rule type could detect problems but would not be able to remediate. To identify which rule types support remediation, you can run: @@ -64,6 +82,10 @@ To identify which rule types support remediation, you can run: minder ruletype list -oyaml ``` -This will show all the rule types; a rule type with a `remediate` attribute supports automatic remediation. +This will show all the rule types; a rule type with a `remediate` attribute +supports automatic remediation. -Furthermore, remediations that open a pull request such as the `dependabot` rule type only attempt to replace the target file, overwriting its contents. This means that if you want to keep the current changes, you need to merge the contents manually. +Furthermore, remediations that open a pull request such as the `dependabot` rule +type only attempt to replace the target file, overwriting its contents. This +means that if you want to keep the current changes, you need to merge the +contents manually. diff --git a/docs/docs/understand/repository_registration.md b/docs/docs/understand/repository_registration.md index 2ecf27f795..30da2c2d97 100644 --- a/docs/docs/understand/repository_registration.md +++ b/docs/docs/understand/repository_registration.md @@ -3,59 +3,80 @@ title: Repository registration sidebar_position: 50 --- -_Registering a repository_ tells Minder to apply the [profiles](profiles.md) that you've defined to that repository. Minder will continuously monitor that repository based on the profiles that you've defined, and optionally [alert you](alerts.md) or [automatically remediate the problem](remediations.md) when the repository is out of compliance. +_Registering a repository_ tells Minder to apply the [profiles](profiles.md) +that you've defined to that repository. Minder will continuously monitor that +repository based on the profiles that you've defined, and optionally +[alert you](alerts.md) or [automatically remediate the problem](remediations.md) +when the repository is out of compliance. ## Registering repositories -Once you have [enrolled the GitHub Provider](providers.md), you can register repositories that you granted Minder access to within GitHub. +Once you have [enrolled the GitHub Provider](providers.md), you can register +repositories that you granted Minder access to within GitHub. -To get a list of repositories, and select them using a menu in Minder's text user interface, run: +To get a list of repositories, and select them using a menu in Minder's text +user interface, run: ```bash minder repo register ``` -You can also register an individual repository by name, or a set of repositories, comma-separated. For example: +You can also register an individual repository by name, or a set of +repositories, comma-separated. For example: ```bash minder repo register --name "owner/repo1,owner/repo2" ``` -After registering repositories, Minder will begin applying your existing profiles to those repositories and will identify repositories that are out of compliance with your security profiles. +After registering repositories, Minder will begin applying your existing +profiles to those repositories and will identify repositories that are out of +compliance with your security profiles. -In addition, Minder will set up a webhook in each repository that was registered. This allows Minder to identify when configuration changes are made to your repositories and re-scan them for compliance with your profiles. +In addition, Minder will set up a webhook in each repository that was +registered. This allows Minder to identify when configuration changes are made +to your repositories and re-scan them for compliance with your profiles. ## Automatically registering new repositories -The GitHub Provider can be configured to automatically register new repositories that are created in your organization. This is done by setting an attribute on the provider. +The GitHub Provider can be configured to automatically register new repositories +that are created in your organization. This is done by setting an attribute on +the provider. -First, identify the _name_ of your GitHub Provider. You can list your enrolled providers by running: +First, identify the _name_ of your GitHub Provider. You can list your enrolled +providers by running: ```bash minder provider list ``` -To enable automatic registration for your future repositories, set the `auto_registration.entities.repository.enabled` attribute to `true` for your provider. For example, if your provider was named `github-app-myorg`, run: +To enable automatic registration for your future repositories, set the +`auto_registration.entities.repository.enabled` attribute to `true` for your +provider. For example, if your provider was named `github-app-myorg`, run: ```bash minder provider update --set-attribute=auto_registration.entities.repository.enabled=true --name=github-app-myorg ``` -To enable automatic registration for existing repositories and enroll all the currently existing repositories, you can use the `minder repo register` command: +To enable automatic registration for existing repositories and enroll all the +currently existing repositories, you can use the `minder repo register` command: + ```bash minder repo register --all ``` -You can pass the `--provider` flag to restrict the registration to a specific provider. By default, the `repo register` command will register repositories for all providers. -To disable automatic registration, set the `auto_registration.entities.repository.enabled` attribute to `false`: +You can pass the `--provider` flag to restrict the registration to a specific +provider. By default, the `repo register` command will register repositories for +all providers. + +To disable automatic registration, set the +`auto_registration.entities.repository.enabled` attribute to `false`: ```bash minder provider update --set-attribute=auto_registration.entities.repository.enabled=false --name=github-app-myorg ``` -:::note -Disabling automatic registration will not remove the repositories that have already been registered. -::: +:::note Disabling automatic registration will not remove the repositories that +have already been registered. ::: ## List and get Repositories @@ -65,7 +86,8 @@ You can list all repositories registered in Minder: minder repo list ``` -You can also get detailed information about a specific repository. For example, to view the information for `owner/repo1`, run: +You can also get detailed information about a specific repository. For example, +to view the information for `owner/repo1`, run: ```bash minder repo get --name owner/repo1 @@ -73,10 +95,12 @@ minder repo get --name owner/repo1 ## Removing a registered repository -If you want to stop monitoring a repository, you can remove it from Minder by using the `repo delete` command: +If you want to stop monitoring a repository, you can remove it from Minder by +using the `repo delete` command: ```bash minder repo delete --name "owner/repo1" ``` -This will remove the repository configuration from Minder and remove the webhook from the GitHub repository. +This will remove the repository configuration from Minder and remove the webhook +from the GitHub repository. diff --git a/docs/docs/understand/rule_evaluation.md b/docs/docs/understand/rule_evaluation.md index c8912623e9..427c2355e8 100644 --- a/docs/docs/understand/rule_evaluation.md +++ b/docs/docs/understand/rule_evaluation.md @@ -5,45 +5,66 @@ sidebar_position: 50 # Rule evaluations -When Minder evaluates the [rules in your profiles](profiles.md), it records the state of those evaluations. When those rules are not satisfied because the criteria that you defined was not met, it will issue [alerts](alerts.md). +When Minder evaluates the [rules in your profiles](profiles.md), it records the +state of those evaluations. When those rules are not satisfied because the +criteria that you defined was not met, it will issue [alerts](alerts.md). Minder evaluates the rules in your profile: -* When the repository is registered -* When the profile is updated -* When activity occurs within the repository + +- When the repository is registered +- When the profile is updated +- When activity occurs within the repository In a rule evaluation, you'll see: -* The time that a rule evaluation was performed -* The entity that was examined (a repository, artifact, or pull request) -* The rule that was evaluated -* The status of the evaluation -* Whether an [alert](alerts.md) was opened -* Whether [automatic remediation](remediations.md) was performed, and if so, its status + +- The time that a rule evaluation was performed +- The entity that was examined (a repository, artifact, or pull request) +- The rule that was evaluated +- The status of the evaluation +- Whether an [alert](alerts.md) was opened +- Whether [automatic remediation](remediations.md) was performed, and if so, its + status ### Viewing rule evaluations -To view the rule evaluations, run [`minder history list`](../ref/cli/minder_history_list.md). You can query the history to only look at certain entities, profiles, or statuses. +To view the rule evaluations, run +[`minder history list`](../ref/cli/minder_history_list.md). You can query the +history to only look at certain entities, profiles, or statuses. ### Evaluation status -The _status_ of a rule evaluation describes the outcome of executing the rule against an entity. Possible statuses are: +The _status_ of a rule evaluation describes the outcome of executing the rule +against an entity. Possible statuses are: -* **Success**: the entity was evaluated and is in compliance with the rule. For example, given the [`secret_scanning`](../ref/rules/secret_scanning.md) rule, this means that secret scanning is enabled on the repository being evaluated. -* **Failure**: the entity was evaluated and is _not_ in compliance with the rule. For example, given the [`secret_scanning`](../ref/rules/secret_scanning.md) rule, this means that secret scanning is _not_ enabled on the repository being evaluated. -* **Error**: the rule could not be evaluated for some reason. For example, the server being evaluated was not online or could not be contacted. -* **Pending**: the rule has not yet been evaluated. Once evaluated, it will move into a state that represents the evaluation. -* **Skipped**: the rule is not configured for the entity. For example, given the [`secret_scanning`](../ref/rules/secret_scanning.md) rule, it can be configured to skip private repositories. +- **Success**: the entity was evaluated and is in compliance with the rule. For + example, given the [`secret_scanning`](../ref/rules/secret_scanning.md) rule, + this means that secret scanning is enabled on the repository being evaluated. +- **Failure**: the entity was evaluated and is _not_ in compliance with the + rule. For example, given the + [`secret_scanning`](../ref/rules/secret_scanning.md) rule, this means that + secret scanning is _not_ enabled on the repository being evaluated. +- **Error**: the rule could not be evaluated for some reason. For example, the + server being evaluated was not online or could not be contacted. +- **Pending**: the rule has not yet been evaluated. Once evaluated, it will move + into a state that represents the evaluation. +- **Skipped**: the rule is not configured for the entity. For example, given the + [`secret_scanning`](../ref/rules/secret_scanning.md) rule, it can be + configured to skip private repositories. ### Alert status -When a rule evaluation occurs, an [alert](alerts.md) may be created. Each rule evaluation has an alert status: +When a rule evaluation occurs, an [alert](alerts.md) may be created. Each rule +evaluation has an alert status: -* **Success**: an alert was created -* **Failure**: there was an issue creating the alert; for example, GitHub failed to create a security advisory -* **Skipped**: the rule evaluation was successful, meaning an alert should not be created, or the profile is not configured to generate alerts +- **Success**: an alert was created +- **Failure**: there was an issue creating the alert; for example, GitHub failed + to create a security advisory +- **Skipped**: the rule evaluation was successful, meaning an alert should not + be created, or the profile is not configured to generate alerts ### Remediation status -* **Success**: the issue was automatically remediated -* **Failure**: the issue could not be automatically remediated -* **Skipped**: the rule evaluation was successful, meaning remediation should not be performed, or the profile is not configured to automatically remediate +- **Success**: the issue was automatically remediated +- **Failure**: the issue could not be automatically remediated +- **Skipped**: the rule evaluation was successful, meaning remediation should + not be performed, or the profile is not configured to automatically remediate diff --git a/docs/docs/user_management/adding_users.md b/docs/docs/user_management/adding_users.md index c2cb178076..378e66bd9b 100644 --- a/docs/docs/user_management/adding_users.md +++ b/docs/docs/user_management/adding_users.md @@ -59,7 +59,7 @@ To add a user to your project, follow these steps: ## Have the User Exercise the Invitation Code Relay the invitation code to the user who you are inviting to join your project. -They will need to install the `minder` CLI and run +They will need to install the `minder` CLI and run `minder auth invite accept ` to accept the invitation. Invitations will expire when used, or after 7 days, though users who have not accepted an invitation can be invited again. diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 48fb016cce..cdf8892e9f 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -10,7 +10,7 @@ * Docusaurus scaffolding. Remove this one it's converted to TypeScript. */ -const lightCodeTheme = require('prism-react-renderer/themes/github') +const lightCodeTheme = require('prism-react-renderer/themes/github'); const darkCodeTheme = require('prism-react-renderer/themes/dracula'); const redocusaurus = [ @@ -26,8 +26,8 @@ const redocusaurus = [ primaryColor: '#000000', primaryColorDark: '#b0e0e6', }, - } -] + }, +]; /** @type {import('@docusaurus/types').Config} */ const config = { @@ -97,13 +97,12 @@ const config = { themeConfig: /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ - ( - { - colorMode: { - defaultMode: 'dark', - disableSwitch: false, - respectPrefersColorScheme: false, - }, + ({ + colorMode: { + defaultMode: 'dark', + disableSwitch: false, + respectPrefersColorScheme: false, + }, // Replace with your project's social card image: 'img/Minder_darkMode.png', navbar: { @@ -117,7 +116,7 @@ const config = { // type: 'html', // position: 'right', // value: 'Minder version:', - // }, + // }, // { // type: 'docsVersionDropdown', // position: 'right', diff --git a/docs/sidebars.js b/docs/sidebars.js index 156f6ff228..f5fa81bc2d 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -1,7 +1,6 @@ // SPDX-FileCopyrightText: Copyright 2023 The Minder Authors // SPDX-License-Identifier: Apache-2.0 - /** * Creating a sidebar enables you to: - create an ordered group of docs @@ -15,7 +14,7 @@ const sidebars = { // By default, Docusaurus generates a sidebar from the docs folder structure - minder: [{type: 'autogenerated', dirName: '.'}], + minder: [{ type: 'autogenerated', dirName: '.' }], }; module.exports = sidebars; diff --git a/docs/src/pages/index.module.css b/docs/src/pages/index.module.css index 34ff7a79dc..d7d5ed4b33 100644 --- a/docs/src/pages/index.module.css +++ b/docs/src/pages/index.module.css @@ -2,7 +2,7 @@ SPDX-FileCopyrightText: Copyright YYYY The Minder Authors SPDX-License-Identifier: Apache-2.0 */ - + /** * CSS files with the .module.css suffix will be treated as CSS modules * and scoped locally. From 6dbfe95ec4115e4b5597c22773e24ca19a519d0a Mon Sep 17 00:00:00 2001 From: Dan Barr Date: Thu, 9 Jan 2025 22:20:49 -0500 Subject: [PATCH 2/4] Lint all docs files --- docs/.markdownlint.json | 1 - docs/docs/about/changelog.md | 2 - docs/docs/about/contributing.md | 6 +- docs/docs/about/roadmap.md | 4 +- docs/docs/developer_guide/_category_.yml | 2 +- docs/docs/developer_guide/feature_flags.md | 13 ++- docs/docs/developer_guide/get-hacking.md | 2 - docs/docs/getting_started/enroll_provider.md | 18 +++-- docs/docs/getting_started/first_profile.md | 14 ++-- docs/docs/getting_started/install_cli.md | 13 ++- docs/docs/getting_started/login.md | 4 +- docs/docs/getting_started/quickstart.md | 10 +-- docs/docs/getting_started/register_repos.md | 6 +- docs/docs/getting_started/remediations.md | 6 +- docs/docs/getting_started/viewing_status.md | 7 +- docs/docs/how-to/artifact_signatures.md | 16 ++-- docs/docs/how-to/create_profile.md | 16 ++-- docs/docs/how-to/create_project.md | 8 +- docs/docs/how-to/custom-rules.md | 79 +++++++++---------- docs/docs/how-to/manage_profiles.md | 6 +- docs/docs/how-to/mindev.md | 4 +- .../how-to/{pr_reviews.md => pr_reviews.mdx} | 13 +-- docs/docs/how-to/profile_selectors.md | 36 ++++----- ...llrequest.md => remediate-pullrequest.mdx} | 11 ++- docs/docs/how-to/setup-alerts.md | 6 +- docs/docs/how-to/setup-autoremediation.md | 6 +- docs/docs/how-to/writing-rules-in-rego.md | 76 +++++++++--------- docs/docs/index.mdx | 4 +- .../integrations/community_integrations.md | 2 - docs/docs/integrations/overview.md | 9 +-- .../provider_integrations/github.md | 9 +-- docs/docs/integrations/stacklok-insight.md | 5 +- docs/docs/ref/cli_configuration.md | 5 +- docs/docs/ref/rules/_category_.yml | 2 +- docs/docs/ref/rules/artifact_signature.md | 10 +-- docs/docs/ref/rules/branch_protection.md | 6 +- docs/docs/ref/rules/codeql_enabled.md | 7 +- docs/docs/ref/rules/dependabot_configured.md | 7 +- docs/docs/ref/rules/github_actions.md | 7 +- docs/docs/ref/rules/license.md | 7 +- docs/docs/ref/rules/pr_trusty_check.md | 11 ++- docs/docs/ref/rules/pr_vulnerability_check.md | 9 +-- docs/docs/ref/rules/secret_scanning.md | 7 +- docs/docs/run_minder_server/_category_.yml | 2 +- docs/docs/run_minder_server/config_oauth.md | 6 +- .../docs/run_minder_server/config_provider.md | 20 +++-- docs/docs/run_minder_server/config_webhook.md | 6 +- .../run_minder_server/installing_minder.md | 47 ++++++----- .../run_minder_server/intro_to_install.md | 2 - docs/docs/run_minder_server/run_the_server.md | 36 ++++----- docs/docs/understand/alerts.md | 4 +- docs/docs/understand/profiles.md | 10 +-- docs/docs/understand/projects.md | 2 - docs/docs/understand/providers.md | 4 +- docs/docs/understand/remediations.md | 6 +- .../understand/repository_registration.md | 16 ++-- docs/docs/understand/rule_evaluation.md | 10 +-- docs/docs/user_management/adding_users.md | 10 +-- docs/docs/user_management/user_roles.md | 5 +- docs/docusaurus.config.js | 2 +- 60 files changed, 311 insertions(+), 369 deletions(-) rename docs/docs/how-to/{pr_reviews.md => pr_reviews.mdx} (95%) rename docs/docs/how-to/{remediate-pullrequest.md => remediate-pullrequest.mdx} (91%) diff --git a/docs/.markdownlint.json b/docs/.markdownlint.json index b79d54ffd2..5190cf21f1 100644 --- a/docs/.markdownlint.json +++ b/docs/.markdownlint.json @@ -20,7 +20,6 @@ "tables": false }, "no-bare-urls": false, - "no-duplicate-heading": false, "proper-names": { "code_blocks": false, "names": ["GitHub", "GitLab", "Bitbucket"] diff --git a/docs/docs/about/changelog.md b/docs/docs/about/changelog.md index ec85fd9d87..10ba4d4594 100644 --- a/docs/docs/about/changelog.md +++ b/docs/docs/about/changelog.md @@ -3,8 +3,6 @@ title: Changelog sidebar_position: 30 --- -# Changelog - - **Profile selectors** - Sep 9, 2024 You can now specify which repositories a profile applies to using a Common Expression Language (CEL) grammar. diff --git a/docs/docs/about/contributing.md b/docs/docs/about/contributing.md index 7cfb29af2a..21a1c188f4 100644 --- a/docs/docs/about/contributing.md +++ b/docs/docs/about/contributing.md @@ -3,16 +3,14 @@ title: Contributing to Minder sidebar_position: 80 --- -# Contributing to Minder - Minder is an open-source project, and we welcome contributions from the community. There are several ways to contribute to Minder, including reporting bugs, suggesting new features, and submitting pull requests with code changes. -## Reporting Security Vulnerabilities +## Reporting security vulnerabilities If you think you have found a security vulnerability in Minder please DO NOT -disclose it publicly until we’ve had a chance to fix it. Please don’t report +disclose it publicly until we've had a chance to fix it. Please don't report security vulnerabilities using GitHub issues; instead, please follow this [process](https://github.com/mindersec/minder/blob/main/SECURITY.md). diff --git a/docs/docs/about/roadmap.md b/docs/docs/about/roadmap.md index c6987b96de..e1ab70069d 100644 --- a/docs/docs/about/roadmap.md +++ b/docs/docs/about/roadmap.md @@ -3,8 +3,6 @@ title: Roadmap sidebar_position: 70 --- -# Roadmap - ## About this roadmap This roadmap should serve as a reference point for Minder users and community @@ -22,7 +20,7 @@ Have any questions or comments about items on the Minder roadmap? Share your feedback via [Minder GitHub Discussions](https://github.com/mindersec/minder/discussions). -_Last updated: June 2024_ +**Last updated:** June 2024 ## In progress diff --git a/docs/docs/developer_guide/_category_.yml b/docs/docs/developer_guide/_category_.yml index 6a22d01ab3..cf5054a2a7 100644 --- a/docs/docs/developer_guide/_category_.yml +++ b/docs/docs/developer_guide/_category_.yml @@ -1,2 +1,2 @@ -label: Developer Guide +label: Developer guide position: 50 diff --git a/docs/docs/developer_guide/feature_flags.md b/docs/docs/developer_guide/feature_flags.md index b3dac26338..8268860c71 100644 --- a/docs/docs/developer_guide/feature_flags.md +++ b/docs/docs/developer_guide/feature_flags.md @@ -1,10 +1,9 @@ --- -title: Feature flags +title: Using feature flags +sidebar_label: Feature flags sidebar_position: 20 --- -# Using Feature Flags - Minder is using [OpenFeature](https://openfeature.dev/) for feature flags. For more complex configuration, refer to that documentation. With that said, our goals are to allow for _simple, straightforward_ usage of feature flags to @@ -36,7 +35,7 @@ Appropriate usages of feature flags: whether a feature is useful to end-users. Feature flags can allow comparing the usage of two groups with and without the feature enabled. -### Inappropriate Use Of Feature Flags +### Inappropriate use of feature flags We expect that feature flags will generally be short-lived (a few months in most cases). There are costs (testing, maintenance, complexity, and general @@ -44,7 +43,7 @@ opportunity costs) to maintaining two code paths, so we aim to retire feature flags once the feature is considered "stable". Here are some examples of alternative mechanisms to use for long-term behavior changes: -- **Server Configuration**. See +- **Server configuration**. See [`internal/config/server`](https://github.com/mindersec/minder/tree/main/internal/config/server) for long-term options that should be on or off at server startup and don't need to change based on the invocation. @@ -54,7 +53,7 @@ alternative mechanisms to use for long-term behavior changes: for functionality that should be able to be turned on or off on a per-project basis (for example, for paid customers). -## How to Use Feature Flags +## How to use feature flags If you're working on a new Minder feature and want to merge it incrementally, check out @@ -79,7 +78,7 @@ behavior over OpenFeature: - We extract the user, project, and provider from `ctx`, so you don't need to. - Eventually, we'll also record the flag settings in our telemetry records (WIP) -## Using Flags During Development +## Using flags during development You can create a `flags-config.yaml` in the root Minder directory when running with `make run-docker`, and the file (and future changes) will be mapped into diff --git a/docs/docs/developer_guide/get-hacking.md b/docs/docs/developer_guide/get-hacking.md index 913cc11176..e2cc23ca64 100644 --- a/docs/docs/developer_guide/get-hacking.md +++ b/docs/docs/developer_guide/get-hacking.md @@ -3,8 +3,6 @@ title: Get hacking sidebar_position: 1 --- -# Get Hacking - ## Run Minder Follow the steps in the diff --git a/docs/docs/getting_started/enroll_provider.md b/docs/docs/getting_started/enroll_provider.md index 579bc43ab5..76e4fea291 100644 --- a/docs/docs/getting_started/enroll_provider.md +++ b/docs/docs/getting_started/enroll_provider.md @@ -1,10 +1,8 @@ --- -title: Enrolling the GitHub Provider +title: Enrolling the GitHub provider sidebar_position: 40 --- -# Enrolling the GitHub Provider - Once you have authenticated to Minder, you'll need to enroll your GitHub credentials to allow Minder to manage your GitHub repositories. This allows Minder to inspect and manage your repository configuration. You will be prompted @@ -14,13 +12,17 @@ In the future, Minder will support other source control and artifact repositories, and you will be able to enroll credentials for those providers in the same manner. -:::note If you used the [minder `quickstart` command](quickstart), the GitHub -Provider was enrolled as part of the quickstart, and you do not need to enroll a -second time. ::: +:::note + +If you used the [minder `quickstart` command](quickstart), the GitHub provider +was enrolled as part of the quickstart, and you do not need to enroll a second +time. + +::: ## Prerequisites -Before you can enroll the GitHub Provider, you must +Before you can enroll the GitHub provider, you must [log in to Minder using the CLI](login). ## Enrolling and granting access @@ -49,5 +51,5 @@ will not be visible within Minder, and you will not be able to You can change your repository selection within GitHub at any time. Once you authorize Minder within GitHub, the browser window will close, and you -will have enrolled the GitHub Provider. The `minder` CLI application will report +will have enrolled the GitHub provider. The `minder` CLI application will report the session is complete. diff --git a/docs/docs/getting_started/first_profile.md b/docs/docs/getting_started/first_profile.md index 8cfb4882c4..c75c5a5f37 100644 --- a/docs/docs/getting_started/first_profile.md +++ b/docs/docs/getting_started/first_profile.md @@ -3,8 +3,6 @@ title: Creating your first profile sidebar_position: 60 --- -# Creating your first profile - Once you have registered repositories, you can create a profile that specifies the common, consistent configuration that you expect your your repositories to comply with. @@ -27,7 +25,7 @@ In this example, Minder will scan the repositories that you've registered and identify any repositories that do not have secret scanning enabled, and those that do not have secret push protection enabled. -### Adding rule types +### Add rule types In Minder, the rule type configuration is completely flexible, and you can author them yourself. Because of this, your Minder organization does not have @@ -56,7 +54,7 @@ minder ruletype create -f secret_scanning.yaml minder ruletype create -f secret_push_protection.yaml ``` -### Creating a profile +### Create the profile Once you have added the rule type definitions to Minder, you can create a profile that uses them to scan your repositories. @@ -89,20 +87,20 @@ repository: Then upload the profile configuration to Minder: -``` +```bash minder profile create -f my_profile.yaml ``` Check the status of the profile: -``` +```bash minder profile status list --name my_profile ``` If all registered repositories have secret scanning enabled, you will see the `OVERALL STATUS` is `Success`, otherwise the overall status is `Failure`. -``` +```plain +--------------------------------------+------------+----------------+----------------------+ | ID | NAME | OVERALL STATUS | LAST UPDATED | +--------------------------------------+------------+----------------+----------------------+ @@ -114,6 +112,6 @@ If secret scanning is not enabled, you will see `Failure` instead of `Success`. See a detailed view of which repositories satisfy the secret scanning rule: -``` +```bash minder profile status list --name my_profile --detailed ``` diff --git a/docs/docs/getting_started/install_cli.md b/docs/docs/getting_started/install_cli.md index 3129b135a7..d471e88934 100644 --- a/docs/docs/getting_started/install_cli.md +++ b/docs/docs/getting_started/install_cli.md @@ -1,16 +1,15 @@ --- -title: Install Minder CLI +title: Installing the Minder CLI +sidebar_label: Install Minder CLI sidebar_position: 10 --- -# Installing the Minder CLI - The open source Minder CLI can communicate with either [the free public instance provided by Stacklok](../../#minder-public-instance), or with a [self managed server](../run_minder_server/run_the_server). The `minder` CLI is built for `amd64` and `arm64` architectures on Windows, -MacOS, and Linux. +macOS, and Linux. You can install `minder` using one of the following methods: @@ -41,13 +40,13 @@ winget install stacklok.minder ``` Alternatively, you can -[download a zipfile containing the `minder` CLI](https://github.com/mindersec/minder/releases) +[download a zip file containing the `minder` CLI](https://github.com/mindersec/minder/releases) and install the binary yourself. ## Linux -We provide pre-built static binaries for Linux at: -https://github.com/mindersec/minder/releases. +We provide pre-built static binaries for Linux at +[https://github.com/mindersec/minder/releases](https://github.com/mindersec/minder/releases). ## Building from source diff --git a/docs/docs/getting_started/login.md b/docs/docs/getting_started/login.md index 3397234592..310f5152ac 100644 --- a/docs/docs/getting_started/login.md +++ b/docs/docs/getting_started/login.md @@ -3,8 +3,6 @@ title: Logging in to Minder sidebar_position: 20 --- -# Logging in to Minder - To start using Minder, you must first log in. Logging in to a Minder server for the first time will create your account. @@ -52,7 +50,7 @@ minder auth login --grpc-host localhost --grpc-port 8090 --identity-url http://l Your web browser will be opened to log in to Keycloak, and then a banner will be printed an -``` +```plain You have successfully logged in. Here are your details: diff --git a/docs/docs/getting_started/quickstart.md b/docs/docs/getting_started/quickstart.md index 67aec8c87f..c966fd5bc9 100644 --- a/docs/docs/getting_started/quickstart.md +++ b/docs/docs/getting_started/quickstart.md @@ -3,8 +3,6 @@ title: Quickstart with Minder (< 1 min) sidebar_position: 30 --- -# Quickstart with Minder (< 1 min) - Minder provides a straightforward "quickstart" functionality that will create your first profile in Minder which ensures that GitHub secret scanning is enabled, and lets you select the GitHub repositories that you want this profile @@ -39,13 +37,13 @@ To get started, run: minder quickstart ``` -#### Enrolling the GitHub provider +### Enrolling the GitHub provider This first step configures GitHub and produces an authentication token that allows Minder to inspect and manage your repository configuration. You will be prompted to grant Minder access. -#### Registering repositories +### Registering repositories This step allows you to select the repositories that you want Minder to manage. Every repository that you select will be scanned according to the profile that @@ -53,7 +51,7 @@ quickstart will set up (next). This profile will ensure that [secret scanning](https://docs.github.com/en/code-security/secret-scanning/about-secret-scanning) is enabled for these repositories. -#### Create the `secret_scanning` rule type +### Create the `secret_scanning` rule type This step will upload the `secret_scanning` rule type to the server. @@ -67,7 +65,7 @@ Minder allows you to build custom rule types, or use But in either case, these rules must be uploaded to the Minder server before you can use them. -#### Create the `quickstart` profile +### Create the `quickstart` profile This step will create a profile named `quickstart-profile` that contains the `secret_scanning` rule type. diff --git a/docs/docs/getting_started/register_repos.md b/docs/docs/getting_started/register_repos.md index 199c94b4c7..355574208e 100644 --- a/docs/docs/getting_started/register_repos.md +++ b/docs/docs/getting_started/register_repos.md @@ -3,18 +3,18 @@ title: Registering repositories sidebar_position: 50 --- -Once you have enrolled the GitHub Provider, you can register your GitHub +Once you have enrolled the GitHub provider, you can register your GitHub repositories with your Minder organization. This will define the repositories that your security profile will apply to. ## Prerequisites Before you can register a repository, you must -[enroll the GitHub Provider](enroll_provider). +[enroll the GitHub provider](enroll_provider). ## Register repositories -Once you have enrolled the GitHub Provider, you can register repositories that +Once you have enrolled the GitHub provider, you can register repositories that you granted Minder access to within GitHub. To get a list of repositories, and select them using a menu in Minder's text diff --git a/docs/docs/getting_started/remediations.md b/docs/docs/getting_started/remediations.md index 59719c1087..11654449a9 100644 --- a/docs/docs/getting_started/remediations.md +++ b/docs/docs/getting_started/remediations.md @@ -3,8 +3,6 @@ title: Automatic remediations sidebar_position: 80 --- -# Automatic remediation with Minder - After you've [created a profile](first_profile), you can [view the status](viewing_status) of your security profile, and you can optionally enable alerts through GitHub Security Advisories. But Minder can also @@ -70,7 +68,7 @@ When remediation is on, the profile status should move quickly through three different states. After disabling secret scanning on a repository, check the status of the profile: -``` +```bash minder profile status list --name my_profile ``` @@ -82,7 +80,7 @@ minder profile status list --name my_profile 3. After Minder has remediated the problem, it will evaluate the rule again. Once this completes, Minder will set the profile `STATUS` to `Success`. -# More information +## More information For more information about automatic remediations, see the [additional documentation in "How Minder works"](../understand/remediations). diff --git a/docs/docs/getting_started/viewing_status.md b/docs/docs/getting_started/viewing_status.md index 7c56712224..9100c75b57 100644 --- a/docs/docs/getting_started/viewing_status.md +++ b/docs/docs/getting_started/viewing_status.md @@ -3,8 +3,6 @@ title: Viewing profile status sidebar_position: 70 --- -# Viewing the status of your profile - When you have created a profile and registered repositories, Minder will evaluate your security profile against those repositories. Minder can report on the status, and can optionally alert you using GitHub Security Advisories. @@ -31,8 +29,7 @@ For example, the profile named `my_profile` expects repositories to have secret scanning enabled. If any repository did not have secret scanning enabled, then the output will look like: -```yaml ---- +```plain +--------------------------------------+------------+----------------+----------------------+ | ID | NAME | OVERALL STATUS | LAST UPDATED | @@ -63,7 +60,7 @@ is indicated by the `STATUS` column set to `Success`. However, that repository does not have secret push protection enabled, which is indicated by the `STATUS` column set to `Failure`. -```yaml +```plain +--------------------------------------+------------------------+------------+---------+-------------+--------------------------------------+ | RULE ID | RULE NAME | ENTITY | STATUS | REMEDIATION | ENTITY INFO | +--------------------------------------+------------------------+------------+---------+-------------+--------------------------------------+ diff --git a/docs/docs/how-to/artifact_signatures.md b/docs/docs/how-to/artifact_signatures.md index 3119b6bfa3..4990c9264b 100644 --- a/docs/docs/how-to/artifact_signatures.md +++ b/docs/docs/how-to/artifact_signatures.md @@ -3,8 +3,6 @@ title: Check artifact provenance sidebar_position: 55 --- -# Check Artifact Provenance - With Minder you can create rules that assert that artifacts built from your repositories are built from trusted sources and using trusted workflows based on their cryptographically signed provenance. @@ -17,7 +15,7 @@ This is done by creating a profile which utilizes the `artifact_signature` - The `minder` CLI application - A Minder account with [at least `editor` permission](../user_management/user_roles.md) -- An enrolled Provider (e.g., GitHub) +- An enrolled provider (e.g., GitHub) - A repository that produces container images. At the moment Minder's artifact signature checks are only available for container images and only the `ghcr.io` registry is supported. @@ -27,19 +25,19 @@ This is done by creating a profile which utilizes the `artifact_signature` Fetch all the reference rules by cloning the [minder-rules-and-profiles repository](https://github.com/mindersec/minder-rules-and-profiles). -``` +```bash git clone https://github.com/mindersec/minder-rules-and-profiles.git ``` In that directory you can find all the reference rules and profiles. -``` +```bash cd minder-rules-and-profiles ``` Create the `artifact_signature` rule type in Minder: -``` +```bash minder ruletype create -f rule-types/github/artifact_signature.yaml ``` @@ -78,7 +76,7 @@ artifact: Create the profile in Minder: -``` +```bash minder profile create -f profile-artifact-simple.yaml ``` @@ -95,7 +93,7 @@ artifact. Create a new file called `profile-artifact-provenance.yaml`. The profile would pass only if the container was built from the `main` branch of the `good-repo-go` repository, using the `build-image-signed-ghat.yml` workflow -using a hosted github runner. +using a hosted GitHub runner. ```yaml --- @@ -122,7 +120,7 @@ artifact: Create the profile in Minder: -``` +```bash minder profile create -f profile-artifact-provenance.yaml ``` diff --git a/docs/docs/how-to/create_profile.md b/docs/docs/how-to/create_profile.md index 69a6594159..73fbff7fbe 100644 --- a/docs/docs/how-to/create_profile.md +++ b/docs/docs/how-to/create_profile.md @@ -20,19 +20,19 @@ get started quickly, create a rule from the set of references. Fetch all the reference rules by cloning the [minder-rules-and-profiles repository](https://github.com/mindersec/minder-rules-and-profiles). -``` +```bash git clone https://github.com/mindersec/minder-rules-and-profiles.git ``` In that directory you can find all the reference rules and profiles. -``` +```bash cd minder-rules-and-profiles ``` Create the `secret_scanning` rule type in Minder: -``` +```bash minder ruletype create -f rule-types/github/secret_scanning.yaml ``` @@ -204,7 +204,7 @@ def: Finally, create the `secret_scanning` rule in Minder: -``` +```bash minder ruletype create -f secret_scanning.yaml ``` @@ -291,12 +291,12 @@ repository `minder` and have failed, run the following command: minder profile status list --name stacklok-remediate-profile -d -ojson 2>/dev/null | jq -C '.ruleEvaluationStatus | map(select(.entityInfo.repo_name == "minder" and .status == "failure"))' ``` -## Defining Rule Names in Profiles +## Defining rule names in profiles In Minder profiles, rules are identified by their type and, optionally, a unique name. -### Rule Types vs Rule Names +### Rule types vs. rule names Rule types are mandatory and refer to the kind of rule being applied. Rule names, on the other hand, are optional identifiers that become crucial when @@ -313,7 +313,7 @@ repository: In this example, `secret_scanning` is the rule type and `secret_scanning_github` is the rule name. -### When are Rule Names Mandatory? +### When are rule names mandatory? If you're using multiple rules of the same type under an entity, each rule must have a unique name. This helps distinguish between rules and understand their @@ -334,7 +334,7 @@ repository: Here, we have two rules of the same type `secret_scanning` under the `repository` entity. Each rule has a unique name. -### Uniqueness of Rule Names +### Uniqueness of rule names No two rules, whether of the same type or different types, can have the same name under an entity. This avoids confusion and ensures each rule can be diff --git a/docs/docs/how-to/create_project.md b/docs/docs/how-to/create_project.md index 50af2902f7..6d264c5913 100644 --- a/docs/docs/how-to/create_project.md +++ b/docs/docs/how-to/create_project.md @@ -1,5 +1,5 @@ --- -title: Creating a New Project +title: Creating a new project sidebar_position: 90 --- @@ -8,7 +8,7 @@ new project to manage your entities (repositories, artifacts, etc). It is also possible to create additional projects after you have created your Minder profile, for example, to create different projects for different organizations or teams you are a part of. Note that -[Minder Projects](../understand/projects.md) can collect resources from several +[Minder projects](../understand/projects.md) can collect resources from several upstream resource providers such as different GitHub organizations, so you can register several [entity providers](../understand/providers.md) within a project. @@ -19,10 +19,10 @@ project. - A GitHub organization you are an administrator for which does not have the Minder app installed on. -## Creating a New Project +## Creating a new project To create a new project, enable a minder -[GitHub application](../run_minder_server/config_provider.md) on a GitHub +[GitHub Application](../run_minder_server/config_provider.md) on a GitHub organization or user account. If the GitHub App is installed on a GitHub organization which is not already registered in Minder, Minder will create a new project to manage those resources. Using diff --git a/docs/docs/how-to/custom-rules.md b/docs/docs/how-to/custom-rules.md index 6d497694ad..604006625a 100644 --- a/docs/docs/how-to/custom-rules.md +++ b/docs/docs/how-to/custom-rules.md @@ -1,9 +1,8 @@ --- +title: Writing custom rule types sidebar_position: 100 --- -# Writing custom rule types - Minder's policy engine is flexible enough that you can write your own rule types to check for specific settings in your supply chain. This guide will walk you through the process of writing a custom rule type. @@ -12,30 +11,30 @@ through the process of writing a custom rule type. Minder allows you to check and enforce that certain settings are set up for several stages in your supply chain. To configure those settings, you need to -create a Profile. This profile is composed of several rules that represent the +create a profile. This profile is composed of several rules that represent the settings you want in your supply chain. These rules are actually instantiations -of another handy object for Minder called Rule Types. These rule types define +of another handy object for Minder called rule types. These rule types define the nitty-gritty details of how the specific setting you care about will be checked, how you'll be alerted when something goes out of order, and how it will be automatically remediated. -You can browse a curated collection of rule types in the [rules and profiles -repository])(https://github.com/mindersec/minder-rules-and-profiles). +You can browse a curated collection of rule types in the +[rules and profiles repository](https://github.com/mindersec/minder-rules-and-profiles). Some of the rules include: -- Verifying if you have GitHub’s secret scanning enabled +- Verifying if you have GitHub's secret scanning enabled - Verifying if your artifacts are signed and verifiable on Sigstore - Verifying that your branch protection settings are secure -## Rule Types +## Rule types -Rule types aren’t particularly complicated. They include the basic structure to +Rule types aren't particularly complicated. They include the basic structure to get an observed state, evaluate the rule based on that observed state, do actions based on that state, and finally, give you some instructions in case you want to manage things manually. -The Rule Type object in YAML looks as follows: +The Rule type object in YAML looks as follows: ```yaml --- @@ -57,11 +56,11 @@ def: The following are the components of a rule type: -- **Description**: What does the rule do? This is handy to browse through rule +- **description**: What does the rule do? This is handy to browse through rule types when building a profile. -- **Guidance**: What do I do if this rule presents a “failure”? This is handy to - inform folks of what to do in case they’re not using automated remediations. -- **in_entity**: What are we evaluating? This defines the entity that’s being +- **guidance**: What do I do if this rule presents a “failure”? This is handy to + inform folks of what to do in case they're not using automated remediations. +- **in_entity**: What are we evaluating? This defines the entity that's being evaluated. It could be repository, artifact, pull_request, and build_environment (coming soon). - **param_schema**: Optional fields to pass to the ingestion (more on this @@ -69,16 +68,16 @@ The following are the components of a rule type: entity. - **rule_schema**: Optional fields to pass to the evaluation (more on this later). This is handy for customizing how a rule is evaluated. -- **Ingest**: This step defines how we get the observed state for an entity. It +- **ingest**: This step defines how we get the observed state for an entity. It could be a simple REST call, a cloning of a git repo, or even a custom action - if it’s a complex rule. -- **Eval**: This is the evaluation stage, which defines the actual rule + if it's a complex rule. +- **eval**: This is the evaluation stage, which defines the actual rule evaluation. -- **Remediation**: How do we fix the issue? This defines the action to be taken +- **remediation**: How do we fix the issue? This defines the action to be taken when we need to fix an issue. This is what happens when you enable automated remediations. -- **Alert**: How do we notify folks about the issue? This may take the form of a - GitHub Security Advisory, but we’ll support more alerting systems in the near +- **alert**: How do we notify folks about the issue? This may take the form of a + GitHub Security Advisory, but we'll support more alerting systems in the near future. ## Example: Automatically delete head branches @@ -87,7 +86,7 @@ Let's write a rule type for checking that GitHub automatically deletes branches after a pull request has been merged. While this is not strictly a security setting, it is a good practice to keep your branches clean to avoid confusion. -### Ingestion / Evaluation +### Ingestion / evaluation The first thing we need to figure out is how to get the observed state of what we want to evaluate on. This is the ingestion part. @@ -116,9 +115,9 @@ def: While you could hard-code the user/org and name of the repository you want to evaluate, that kind of rule is not handy, especially if you want to enroll multiple repositories in Minder. Thus, Minder has a templating system that -allows you to base multiple parts of the rule type on the entity you’re +allows you to base multiple parts of the rule type on the entity you're evaluating (remember the in_entity part of the rule type?). The fields you may -use are part of the entity’s protobuf, which can be found in +use are part of the entity's protobuf, which can be found in [our documentation](https://minder-docs.stacklok.dev/ref/proto#repository). Now, we want to tell Minder what to actually evaluate from that state. This is @@ -159,7 +158,7 @@ registered for our rule type. ### Alerting -We'll now describe how you may get a notification if your repository doesn’t +We'll now describe how you may get a notification if your repository doesn't adhere to the rule. This is as simple as adding the following to the manifest: ```yaml @@ -171,18 +170,18 @@ def: severity: 'low' ``` -This will create a security advisory in your GitHub repository that you’ll be +This will create a security advisory in your GitHub repository that you'll be able to browse for information. Minder knows already what information to fill-in to make the alert relevant. ### Remediation Minder has the ability to auto-fix issues that it finds in your supply chain, -let’s add an automated fix to this rule! Similarly to ingestion, remediations +let's add an automated fix to this rule! Similarly to ingestion, remediations also have several flavors or types. For our case, a simple REST remediation suffices. -Let’s see how it would look: +Let's see how it would look: ```yaml --- @@ -197,11 +196,11 @@ def: ``` This effectively would do a PATCH REST call to the GitHub API if it finds that -the rule is out of compliance. We’re able to parametrize the call with whatever -we defined in the profile using golang templates (that’s the -`{{ .Profile.enabled }}` section you see in the message’s body). +the rule is out of compliance. We're able to parametrize the call with whatever +we defined in the profile using golang templates (that's the +`{{ .Profile.enabled }}` section you see in the message's body). -### Description & Guidance +### Description & guidance There are a couple of sections that allow us to give information to rule type users about the rule and what to do with it. These are the description and @@ -233,23 +232,23 @@ guidance: | ## Trying the rule out The whole rule can be seen in the -[Rules and Profiles GitHub repository](https://github.com/mindersec/minder-rules-and-profiles). -In order to try it out, we’ll use the minder CLI, which points to the Minder +[rules and profiles GitHub repository](https://github.com/mindersec/minder-rules-and-profiles). +In order to try it out, we'll use the minder CLI, which points to the Minder server hosted by your friends at Stacklok. Before continuing, make sure you use our Quickstart to install the CLI and enroll your GitHub repos. -Let’s create the rule: +Let's create the rule: ```bash -$ minder ruletype create -f rules/github/automatic_branch_deletion.yaml +minder ruletype create -f rules/github/automatic_branch_deletion.yaml ``` Here, you can already see how the description gets displayed. This same description will be handy when browsing rules through `minder ruletype list`. -Let’s now try it out! We can call our rule in a profile as follows: +Let's now try it out! We can call our rule in a profile as follows: ```yaml --- @@ -266,16 +265,16 @@ repository: enabled: true ``` -We’ll call this degustation-profile.yaml. Let’s create it! +We'll call this degustation-profile.yaml. Let's create it! ```bash -$ minder profile create -f degustation-profile.yaml +minder profile create -f degustation-profile.yaml ``` Now, let's view the status of the profile: ```bash -$ minder profile status list -n degustation-profile -d +minder profile status list -n degustation-profile -d ``` Depending on how your repository is set up, you may see a failure or a success. @@ -284,7 +283,7 @@ fixes the issue for you. ## Conclusion -We’ve now created a basic new rule for Minder. There are more ingestion types, +We've now created a basic new rule for Minder. There are more ingestion types, rule evaluation engines, and remediation types that we can use today, and there will be more in the future! If you need support writing your own rule types, feel free to reach out to the Minder team. diff --git a/docs/docs/how-to/manage_profiles.md b/docs/docs/how-to/manage_profiles.md index 85be4928c7..2d515942e4 100644 --- a/docs/docs/how-to/manage_profiles.md +++ b/docs/docs/how-to/manage_profiles.md @@ -3,10 +3,8 @@ title: Manage profiles and compliance sidebar_position: 20 --- -# Manage profiles - In order to detect security deviations from repositories or other entities, -Minder is relying on the concepts of **Profiles**. A profile is a definition of +Minder is relying on the concepts of **profiles**. A profile is a definition of a verification we want to do on an entity in a pipeline. A **profile** is an instance of a profile type and applies to all repositories in a project, with the relevant settings filled in. @@ -186,7 +184,7 @@ into use by creating a profile. ## Create a profile -When there is a need to control the specific behaviours for a set of +When there is a need to control the specific behaviors for a set of repositories, a profile can be created, based on the previous profile types. A profile needs to be associated with a provider, created within a certain diff --git a/docs/docs/how-to/mindev.md b/docs/docs/how-to/mindev.md index 64f7226bab..a6693f3942 100644 --- a/docs/docs/how-to/mindev.md +++ b/docs/docs/how-to/mindev.md @@ -1,9 +1,9 @@ --- +title: Using Mindev to develop and debug rule types +sidebar_label: Develop and debug rule types sidebar_position: 120 --- -# Using Mindev to develop and debug rule types - [Mindev](https://github.com/mindersec/minder/tree/main/cmd/dev) is a tool that helps you develop and debug rule types for Minder. It provides a way to run rule types locally and test them against your codebase. diff --git a/docs/docs/how-to/pr_reviews.md b/docs/docs/how-to/pr_reviews.mdx similarity index 95% rename from docs/docs/how-to/pr_reviews.md rename to docs/docs/how-to/pr_reviews.mdx index 309cecfbef..45af4add0a 100644 --- a/docs/docs/how-to/pr_reviews.md +++ b/docs/docs/how-to/pr_reviews.mdx @@ -3,14 +3,15 @@ title: Enabling pull request reviews sidebar_position: 50 --- -import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; ## Prerequisites - The `minder` CLI application - A Minder account with [at least `editor` permission](../user_management/user_roles.md) -- An enrolled Provider (e.g., GitHub) and registered repositories +- An enrolled provider (e.g., GitHub) and registered repositories ## Create the PR vulnerability check rule @@ -32,19 +33,19 @@ This is a reference rule provider by the Minder team. Fetch all the reference rules by cloning the [minder-rules-and-profiles repository](https://github.com/mindersec/minder-rules-and-profiles). -``` +```bash git clone https://github.com/mindersec/minder-rules-and-profiles.git ``` In that directory you can find all the reference rules and profiles. -``` +```bash cd minder-rules-and-profiles ``` Create the `pr_vulnerability_check` rule type in Minder: -``` +```bash minder ruletype create -f rule-types/github/pr_vulnerability_check.yaml ``` @@ -134,7 +135,7 @@ pull_request: Create the profile in Minder: -``` +```bash minder profile create -f profile.yaml ``` diff --git a/docs/docs/how-to/profile_selectors.md b/docs/docs/how-to/profile_selectors.md index ad7154e02a..a85136c862 100644 --- a/docs/docs/how-to/profile_selectors.md +++ b/docs/docs/how-to/profile_selectors.md @@ -1,10 +1,8 @@ --- -sidebar_position: 130 title: Apply a profile to a subset of entities +sidebar_position: 130 --- -# Apply a profile to a subset of entities - Profiles allow you to apply a consistent set of rules to a group of entities within your project. By default, these profiles are applied universally across all entities in a project. However, you may need to target a specific subset, @@ -17,7 +15,7 @@ entities a profile applies to. - The `minder` CLI application - A Minder account with [at least `editor` permission](../user_management/user_roles.md) -- An enrolled Provider (e.g., GitHub) and registered repositories +- An enrolled provider (e.g., GitHub) and registered repositories ## Add a selector to a profile @@ -82,7 +80,7 @@ while the properties are provider-specific and prefixed with the provider name. | `name` | The full name of the repository, e.g. mindersec/minder | string | | `is_fork` | `true` if the repository is a fork, `nil` if unknown or not applicable to this provider | bool | | `is_private` | `true` if the repository is private, `nil` if unknown or not applicable to this provider | bool | -| `provider` | The provider of the repository, for more details see [Provider Selectors](#entity-provider-selectors) | ProviderSelector | +| `provider` | The provider of the repository, for more details see [Provider selectors](#entity-provider-selectors) | ProviderSelector | ## Repository properties set by the GitHub provider @@ -91,9 +89,9 @@ while the properties are provider-specific and prefixed with the provider name. | `github/license` | The license of the repository, e.g. MIT, GPL, Apache-2.0, etc. | string | | `github/primary_language` | The primary language of the repository, e.g. Go, Python, Java, etc. | string | | `github/default_branch` | The default branch of the repository, e.g. `main`, `master`, etc. | string | -| `github/repo_id` | The github repo ID | integer | -| `github/repo_name` | The github repo name (e.g. `stacklok`) | string | -| `github/repo_owner` | The github repo owner (e.g. `minder`) | string | +| `github/repo_id` | The GitHub repo ID | integer | +| `github/repo_name` | The GitHub repo name (e.g. `stacklok`) | string | +| `github/repo_owner` | The GitHub repo owner (e.g. `minder`) | string | ## Artifact selectors @@ -101,7 +99,7 @@ while the properties are provider-specific and prefixed with the provider name. | ---------- | --------------------------------------------------------------------------------------------------- | ---------------- | | `name` | The full name of the artifact, e.g. mindersec/minder-server | string | | `type` | The type of the artifact, e.g. "container" | string | -| `provider` | The provider of the artifact, for more details see [Provider Selectors](#entity-provider-selectors) | ProviderSelector | +| `provider` | The provider of the artifact, for more details see [Provider selectors](#entity-provider-selectors) | ProviderSelector | ## Artifact properties set by the GitHub provider @@ -112,9 +110,9 @@ while the properties are provider-specific and prefixed with the provider name. | `github/type` | The type of the artifact, e.g. "container" | string | | `github/visibility` | The visibility of the artifact, e.g. "public" | string | | `github/owner` | The full name of the artifact owner. Can be a repo or an org. | string | -| `github/repo` | The github repo full name (e.g. `mindersec/minder`). Empty for org packages. | string | -| `github/repo_name` | The github repo name (e.g. `stacklok`). Empty for org packages. | string | -| `github/repo_owner` | The github repo owner (e.g. `minder`). Empty for org packages. | string | +| `github/repo` | The GitHub repo full name (e.g. `mindersec/minder`). Empty for org packages. | string | +| `github/repo_name` | The GitHub repo name (e.g. `stacklok`). Empty for org packages. | string | +| `github/repo_owner` | The GitHub repo owner (e.g. `minder`). Empty for org packages. | string | ## Pull request selectors @@ -129,15 +127,15 @@ while the properties are provider-specific and prefixed with the provider name. | `github/pull_url` | The URL of the pull request | string | | `github/pull_number` | The number of the pull request | string | | `github/pull_author_id` | The numerical ID of the author of the pull request | int | -| `github/pull_author_login` | The github login of the author of the pull request | string | -| `github/repo_name` | The github repo name (e.g. `stacklok`). | string | -| `github/repo_owner` | The github repo owner (e.g. `minder`). | string | +| `github/pull_author_login` | The GitHub login of the author of the pull request | string | +| `github/repo_name` | The GitHub repo name (e.g. `stacklok`). | string | +| `github/repo_owner` | The GitHub repo owner (e.g. `minder`). | string | ## Entity provider selectors Each entity can be filtered based on its provider. -| Field | Description | Type | -| ------- | -------------------------------------------------- | ------ | -| `name` | The name of the provider, e.g. github-app-stacklok | string | -| `class` | The class of the provider, e.g. github-app | string | +| Field | Description | Type | +| ------- | ---------------------------------------------------- | ------ | +| `name` | The name of the provider, e.g. `github-app-stacklok` | string | +| `class` | The class of the provider, e.g. `github-app` | string | diff --git a/docs/docs/how-to/remediate-pullrequest.md b/docs/docs/how-to/remediate-pullrequest.mdx similarity index 91% rename from docs/docs/how-to/remediate-pullrequest.md rename to docs/docs/how-to/remediate-pullrequest.mdx index 4770847194..dc5f36db1a 100644 --- a/docs/docs/how-to/remediate-pullrequest.md +++ b/docs/docs/how-to/remediate-pullrequest.mdx @@ -1,20 +1,19 @@ --- -title: Automatic remediation via Pull Request +title: Automatic remediation via pull request sidebar_position: 65 --- -import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; - -# Creating a pull request for automatic remediation +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; ## Prerequisites - The `minder` CLI application - A Minder account with [at least `editor` permission](../user_management/user_roles.md) -- An enrolled Provider (e.g., GitHub) and registered repositories +- An enrolled provider (e.g., GitHub) and registered repositories -## Create a rule type that has support for pull request automatic remediation +## Create a rule type for automatic remediation via pull request The pull request automatic remediation feature provides the functionality to fix a failed rule type by creating a pull request. diff --git a/docs/docs/how-to/setup-alerts.md b/docs/docs/how-to/setup-alerts.md index 6267977a3f..d29677fdda 100644 --- a/docs/docs/how-to/setup-alerts.md +++ b/docs/docs/how-to/setup-alerts.md @@ -3,16 +3,14 @@ title: Setting up a profile for GitHub Security Advisories sidebar_position: 70 --- -# Setting up a profile for GitHub Security Advisories - ## Prerequisites - The `minder` CLI application - A Minder account with [at least `editor` permission](../user_management/user_roles.md) -- An enrolled Provider (e.g., GitHub) and registered repositories +- An enrolled provider (e.g., GitHub) and registered repositories -## Create a rule type that you want to be alerted on +## Create a rule type for alerting The `alert` feature is available for all rule types that have the `alert` section defined in their `.yaml` file. Alerts are a core feature of diff --git a/docs/docs/how-to/setup-autoremediation.md b/docs/docs/how-to/setup-autoremediation.md index 5f42aae7b8..c62fc0af35 100644 --- a/docs/docs/how-to/setup-autoremediation.md +++ b/docs/docs/how-to/setup-autoremediation.md @@ -3,16 +3,14 @@ title: Setting up a profile for automatic remediation sidebar_position: 60 --- -# Setting up a Profile for automatic remediation - ## Prerequisites - The `minder` CLI application - A Minder account with [at least `editor` permission](../user_management/user_roles.md) -- An enrolled Provider (e.g., GitHub) and registered repositories +- An enrolled provider (e.g., GitHub) and registered repositories -## Create a rule type that you want to use auto-remediation on +## Create a rule type for auto-remediation The `remediate` feature is available for all rule types that have the `remediate` section defined in their `.yaml` file. When the diff --git a/docs/docs/how-to/writing-rules-in-rego.md b/docs/docs/how-to/writing-rules-in-rego.md index 5dd9290ac4..b8c7aa8d35 100644 --- a/docs/docs/how-to/writing-rules-in-rego.md +++ b/docs/docs/how-to/writing-rules-in-rego.md @@ -1,52 +1,51 @@ --- +title: Writing rules using Rego sidebar_position: 110 --- -# Writing rules using Rego - Minder's policy engine is able to use pluggable drivers for evaluating rules. Rego is a language specifically designed for expressing policies in a clear and concise manner. Its declarative syntax makes it an excellent choice for defining policy logic. In the context of Minder, Rego plays a central role in crafting -Rule Types, which are used to enforce security policies. +rule types, which are used to enforce security policies. -# Writing Rule Types in Minder +## Writing rule types in Minder -Minder organizes policies into Rule Types, each with specific sections defining +Minder organizes policies into rule types, each with specific sections defining how policies are ingested, evaluated, and acted upon. Rule types are then called within profiles to express the security posture of your organization. Let's -delve into the essential components of a Minder Rule Type: +delve into the essential components of a Minder rule type: -- Ingesting Data: Fetching relevant data, often from external sources like +- Ingesting data: Fetching relevant data, often from external sources like GitHub API. - Evaluation: Applying policy logic to the ingested data. Minder offers a set of engines to evaluate data: jq and rego being general-purpose engines, while Stacklok Insight and vulncheck are more use case-specific ones. -- Remediation and Alerting: Taking actions or providing notifications based on +- Remediation and alerting: Taking actions or providing notifications based on evaluation results. E.g. creating a pull request or generating a GitHub security advisory. -## Rego Evaluation types +## Rego evaluation types With Rego being a flexible policy language, it allowed us to express policy checks via different constructs. We chose to implement two in Minder: - **deny-by-default**: Checks for an allowed boolean being set to true, and - denies the policy if it’s not the case. + denies the policy if it's not the case. - **constraints**: Checks for violations in the given policy. This allows us to express the violations and output them in a user friendly-manner. -Note that these are known patterns in the OPA community, so we’re not doing +Note that these are known patterns in the OPA community, so we're not doing anything out of the ordinary here. Instead, we leverage best practices that have already been established. ## Custom Rego functions Given the context in which Minder operates, we did need to add some custom -functionality that OPA doesn’t provide out of the box. Namely, we added the +functionality that OPA doesn't provide out of the box. Namely, we added the following custom functions: - **file.exists(filepath)**: Verifies that the given filepath exists in the Git @@ -95,10 +94,10 @@ pull request context. In addition, most of the [standard OPA functions are available in the Minder runtime](https://www.openpolicyagent.org/docs/latest/policy-reference/#built-in-functions). -## Example: CodeQL-Enabled Check +## Example: CodeQL-enabled check CodeQL is a very handy tool that GitHub provides to do static analysis on -codebases. In this scenario, we’ll see a rule type that verifies that it’s +codebases. In this scenario, we'll see a rule type that verifies that it's enabled via a GitHub action in the repository. ```yaml @@ -179,13 +178,13 @@ def: severity: 'medium' ``` -The rego evaluation uses the `deny-by-default` type. It’ll set the policy as +The rego evaluation uses the `deny-by-default` type. It'll set the policy as successful if there is a GitHub workflow that instantiates `github/codeql-action/analyze`. -## Example: No 'latest' tag in Dockerfile +## Example: no 'latest' tag in Dockerfile -In this scenario, we’ll explore a Rule Type that verifies that a Dockerfile does +In this scenario, we'll explore a rule type that verifies that a Dockerfile does not use the `latest` tag. ```yaml @@ -248,9 +247,9 @@ This leverages the constraints Rego evaluation type, which will output a failure for each violation that it finds. This is handy for usability, as it will tell us exactly the lines that are not in conformance with our rules. -## Example: Security Advisories Check +## Example: security advisories check -This is a more complex example. Here, we'll explore a Rule Type that checks for +This is a more complex example. Here, we'll explore a rule type that checks for open security advisories in a GitHub repository. ```yaml @@ -313,12 +312,12 @@ def: import future.keywords.in severity_to_number := { - null: -1, - "unknown": -1, - "low": 0, - "medium": 1, - "high": 2, - "critical": 3, + null: -1, + "unknown": -1, + "low": 0, + "medium": 1, + "high": 2, + "critical": 3, } default threshold := 1 @@ -326,30 +325,30 @@ def: threshold := severity_to_number[input.profile.severity] if input.profile.severity != null above_threshold(severity, threshold) if { - severity_to_number[severity] >= threshold + severity_to_number[severity] >= threshold } had_fallback if { - input.ingested.fallback + input.ingested.fallback } violations contains {"msg": "Security advisories not enabled."} if { - had_fallback + had_fallback } violations contains {"msg": "Found open security advisories in or above threshold"} if { - not had_fallback + not had_fallback - some adv in input.ingested + some adv in input.ingested - # Is not withdrawn - adv.withdrawn_at == null + # Is not withdrawn + adv.withdrawn_at == null - adv.state != "closed" - adv.state != "published" + adv.state != "closed" + adv.state != "published" - # We only care about advisories that are at or above the threshold - above_threshold(adv.severity, threshold) + # We only care about advisories that are at or above the threshold + above_threshold(adv.severity, threshold) } alert: type: security_advisory @@ -389,8 +388,9 @@ This introductory guide provides a foundation for leveraging Rego and Minder to write policies effectively. Experiment, explore, and tailor these techniques to meet the unique requirements of your projects. -Minder is constantly evolving, so don’t be surprised if we soon add more custom +Minder is constantly evolving, so don't be surprised if we soon add more custom functions or even more evaluation engines! The project is in full steam and more features are coming! -[You can see a list of rule types that we actively maintain here.](https://github.com/mindersec/minder-rules-and-profiles) +You can see a collection of rule types that we actively maintain in the +[minder-rules-and-profiles repo](https://github.com/mindersec/minder-rules-and-profiles) diff --git a/docs/docs/index.mdx b/docs/docs/index.mdx index 24a77e2b9f..3d531e6601 100644 --- a/docs/docs/index.mdx +++ b/docs/docs/index.mdx @@ -1,5 +1,5 @@ --- -title: Minder +sidebar_label: Introduction sidebar_position: 1 --- @@ -17,7 +17,7 @@ import ThemedImage from '@theme/ThemedImage'; # What is Minder? Minder is an open source platform that helps development teams and open source -communities build more secure software, and prove to others that what they’ve +communities build more secure software, and prove to others that what they've built is secure. Minder helps project owners proactively manage their security posture by providing a set of checks and policies to minimize risk along the software supply chain, and attest their security practices to downstream diff --git a/docs/docs/integrations/community_integrations.md b/docs/docs/integrations/community_integrations.md index 4da166b8fa..871d634be1 100644 --- a/docs/docs/integrations/community_integrations.md +++ b/docs/docs/integrations/community_integrations.md @@ -3,8 +3,6 @@ title: OSS tooling integrations sidebar_position: 30 --- -# OSS Tooling Integrations - Minder's policy engine is flexible enough to integrate with a variety of open source tools. This allows you to leverage the tools you already use to make better decisions about your supply chain. diff --git a/docs/docs/integrations/overview.md b/docs/docs/integrations/overview.md index 5a6b67c65a..1d57689ada 100644 --- a/docs/docs/integrations/overview.md +++ b/docs/docs/integrations/overview.md @@ -1,10 +1,9 @@ --- -title: Overview +title: Minder integrations +sidebar_label: Overview sidebar_position: 10 --- -# Minder Integrations - Minder, as a platform, supports multiple integrations with different aspects of your supply chain, as well as sources of information to make relevant decisions. @@ -17,7 +16,7 @@ Think of them as device drivers in an operating system. They provide a common interface to interact with different services. For more information, see the -[Provider Integrations](provider_integrations/github.md) documentation. +[Provider integrations](provider_integrations/github.md) documentation. ## Integration with other tools @@ -31,7 +30,7 @@ Examples of integrations include: - CI/CD tools (e.g. GitHub Actions) - Automated dependency update tools (e.g. Dependabot) -For more information, see the [OSS Integrations](community_integrations.md) +For more information, see the [OSS integrations](community_integrations.md) documentation. ## Stacklok Insight diff --git a/docs/docs/integrations/provider_integrations/github.md b/docs/docs/integrations/provider_integrations/github.md index e8046553ce..1aa3242ea0 100644 --- a/docs/docs/integrations/provider_integrations/github.md +++ b/docs/docs/integrations/provider_integrations/github.md @@ -1,10 +1,9 @@ --- -title: GitHub +title: GitHub provider +sidebar_label: GitHub sidebar_position: 10 --- -# Providers - A provider connects Minder to your software supply chain. It lets Minder know where to look for your repositories, artifacts, and other entities are, in order to make them available for registration. It also tells Minder how to interact @@ -21,7 +20,7 @@ Stay tuned as we add more providers in the future! To enroll GitHub as a provider, use the following command: -``` +```bash minder provider enroll ``` @@ -56,7 +55,7 @@ The provider configuration file should be a JSON file with the following format: See the following section for provider configuration reference -### GitHub App Provider Configuration reference +### GitHub App provider configuration reference The GitHub App provider has the following configuration options: diff --git a/docs/docs/integrations/stacklok-insight.md b/docs/docs/integrations/stacklok-insight.md index d9cdbb1b64..051fcd4863 100644 --- a/docs/docs/integrations/stacklok-insight.md +++ b/docs/docs/integrations/stacklok-insight.md @@ -1,10 +1,9 @@ --- -title: Stacklok Insight +title: Stacklok Insight integration +sidebar_label: Stacklok Insight sidebar_position: 40 --- -# Stacklok Insight Integration - Minder integrates directly with [Stacklok Insight](http://insight.stacklok.com) to enable policy-driven dependency management based on the risk level of dependencies. diff --git a/docs/docs/ref/cli_configuration.md b/docs/docs/ref/cli_configuration.md index a00e7a46f5..6b0724049a 100644 --- a/docs/docs/ref/cli_configuration.md +++ b/docs/docs/ref/cli_configuration.md @@ -1,4 +1,7 @@ -# Minder CLI configuration +--- +title: Minder CLI configuration +sidebar_position: 10 +--- The Minder CLI application is configured using a YAML file. The default location for the configuration file is `$PWD/config.yaml`. You can specify a different diff --git a/docs/docs/ref/rules/_category_.yml b/docs/docs/ref/rules/_category_.yml index e5eafeb33f..bb372eec7c 100644 --- a/docs/docs/ref/rules/_category_.yml +++ b/docs/docs/ref/rules/_category_.yml @@ -1,2 +1,2 @@ label: Rules -position: 20 +position: 30 diff --git a/docs/docs/ref/rules/artifact_signature.md b/docs/docs/ref/rules/artifact_signature.md index 72402b304a..3db8f894ee 100644 --- a/docs/docs/ref/rules/artifact_signature.md +++ b/docs/docs/ref/rules/artifact_signature.md @@ -1,10 +1,8 @@ --- -title: Artifact signature -sidebar_position: 90 +title: Artifact signature verification +sidebar_position: 10 --- -# Artifact signature verification - The following rule type is available for checking that an artifact has a valid signature and its provenance conforms to a policy. @@ -21,7 +19,7 @@ signature is valid. - `artifact_signature` -## Rule Parameters +## Rule parameters - `tags` - the tags that should be checked for signatures. If not specified, all tags will be checked. If specified, the artifact must be tagged with all of @@ -35,7 +33,7 @@ signature is valid. It is an error to specify both `tags` and `tags_regex`. -## Rule Definition Options +## Rule definition options The `artifact_signature` rule has the following options: diff --git a/docs/docs/ref/rules/branch_protection.md b/docs/docs/ref/rules/branch_protection.md index 13e3abf833..a9f2c06f59 100644 --- a/docs/docs/ref/rules/branch_protection.md +++ b/docs/docs/ref/rules/branch_protection.md @@ -1,10 +1,8 @@ --- -title: Branch protections -sidebar_position: 10 +title: Branch protection rules +sidebar_position: 20 --- -# Branch Protection Rules - The following rule type is available for branch protection. ## `branch_protection_allow_deletions` - Whether the branch can be deleted diff --git a/docs/docs/ref/rules/codeql_enabled.md b/docs/docs/ref/rules/codeql_enabled.md index 4055bbc55b..6dfd40245d 100644 --- a/docs/docs/ref/rules/codeql_enabled.md +++ b/docs/docs/ref/rules/codeql_enabled.md @@ -1,10 +1,9 @@ --- -title: Code scanning -sidebar_position: 40 +title: Code Scanning (CodeQL) rule +sidebar_label: Code scanning +sidebar_position: 30 --- -# Code Scanning (CodeQL) Rule - The following rule type is available for Code Scanning (CodeQL). ## `codeql_enabled` - Verifies that CodeQL is enabled for the repository diff --git a/docs/docs/ref/rules/dependabot_configured.md b/docs/docs/ref/rules/dependabot_configured.md index 8c29efa514..c5236f80a2 100644 --- a/docs/docs/ref/rules/dependabot_configured.md +++ b/docs/docs/ref/rules/dependabot_configured.md @@ -1,10 +1,9 @@ --- -title: Dependabot -sidebar_position: 30 +title: Dependabot rule +sidebar_label: Dependabot +sidebar_position: 40 --- -# Dependabot Rule - The following rule type is available for Dependabot. ## `dependabot_configured` - Verifies that Dependabot is configured for the repository diff --git a/docs/docs/ref/rules/github_actions.md b/docs/docs/ref/rules/github_actions.md index 7c740b1267..1af02fdf4a 100644 --- a/docs/docs/ref/rules/github_actions.md +++ b/docs/docs/ref/rules/github_actions.md @@ -1,10 +1,9 @@ --- -title: GitHub Actions -sidebar_position: 70 +title: GitHub Actions configuration rules +sidebar_label: GitHub Actions +sidebar_position: 50 --- -# GitHub Actions Configuration Rules - There are several rule types that can be used to configure GitHub Actions. ## `github_actions_allowed` - Which actions are allowed to be used diff --git a/docs/docs/ref/rules/license.md b/docs/docs/ref/rules/license.md index 0a1df65f55..05067b5005 100644 --- a/docs/docs/ref/rules/license.md +++ b/docs/docs/ref/rules/license.md @@ -1,10 +1,9 @@ --- -title: Presence of a license file -sidebar_position: 80 +title: Presence of a license file rule +sidebar_label: Presence of a license file +sidebar_position: 70 --- -# Presence of a License File Rule - The following rule type is available for verifying if a license file is present and it is of a certain type. diff --git a/docs/docs/ref/rules/pr_trusty_check.md b/docs/docs/ref/rules/pr_trusty_check.md index f896836b8d..32ae619227 100644 --- a/docs/docs/ref/rules/pr_trusty_check.md +++ b/docs/docs/ref/rules/pr_trusty_check.md @@ -1,10 +1,9 @@ --- -title: Stacklok Insight check -sidebar_position: 20 +title: Stacklok Insight rule +sidebar_label: Stacklok Insight check +sidebar_position: 90 --- -# Stacklok Insight Rule - The following rule type is available to check dependency risk with [Stacklok Insight](https://insight.stacklok.com/). @@ -25,11 +24,11 @@ as failed. - `pr_trusty_check` -## Rule Parameters +## Rule parameters - None -## Rule Definition Options +## Rule definition options The `pr_trusty_check` rule supports the following options: diff --git a/docs/docs/ref/rules/pr_vulnerability_check.md b/docs/docs/ref/rules/pr_vulnerability_check.md index 4365e779d0..172d7cca18 100644 --- a/docs/docs/ref/rules/pr_vulnerability_check.md +++ b/docs/docs/ref/rules/pr_vulnerability_check.md @@ -1,10 +1,9 @@ --- -title: Known vulnerabilities +title: Known vulnerabilities rule +sidebar_label: Known vulnerabilities sidebar_position: 60 --- -# Known Vulnerabilities Rule - The following rule type is available for known vulnerabilities. ## `pr_vulnerability_check` - Verifies that pull requests do not add dependencies with known vulnerabilities @@ -22,11 +21,11 @@ request will be rejected or commented on. - `pr_vulnerability_check` -### Rule Parameters +### Rule parameters - None -### Rule Definition Options +### Rule definition options The `pr_vulnerability_check` rule has the following options: diff --git a/docs/docs/ref/rules/secret_scanning.md b/docs/docs/ref/rules/secret_scanning.md index 0151e85968..829ddcf01b 100644 --- a/docs/docs/ref/rules/secret_scanning.md +++ b/docs/docs/ref/rules/secret_scanning.md @@ -1,10 +1,9 @@ --- -title: Secret scanning -sidebar_position: 50 +title: Secret scanning rule +sidebar_label: Secret scanning +sidebar_position: 80 --- -# Secret Scanning Rule - The following rule type is available for secret scanning. ## `secret_scanning` - Verifies that secret scanning is enabled for a given repository diff --git a/docs/docs/run_minder_server/_category_.yml b/docs/docs/run_minder_server/_category_.yml index 7f2ab8a23d..4d5e05fc7e 100644 --- a/docs/docs/run_minder_server/_category_.yml +++ b/docs/docs/run_minder_server/_category_.yml @@ -1,2 +1,2 @@ -label: Run a Minder Server +label: Run a Minder server position: 70 diff --git a/docs/docs/run_minder_server/config_oauth.md b/docs/docs/run_minder_server/config_oauth.md index 155a77f9a2..7476fad85f 100644 --- a/docs/docs/run_minder_server/config_oauth.md +++ b/docs/docs/run_minder_server/config_oauth.md @@ -1,6 +1,6 @@ --- -title: Create a GitHub OAuth Application -sidebar_position: 120 +title: Create a GitHub OAuth application +sidebar_position: 70 --- ## Prerequisites @@ -28,4 +28,4 @@ application. 8. Copy the "Client ID" , "Client Secret" and "Authorization callback URL" values into your `./server-config.yaml` file, under the `github` section. -![github oauth2 page](./images/minder-server-oauth.png) +![GitHub OAuth2 page](./images/minder-server-oauth.png) diff --git a/docs/docs/run_minder_server/config_provider.md b/docs/docs/run_minder_server/config_provider.md index cd7aaaecdf..b163758749 100644 --- a/docs/docs/run_minder_server/config_provider.md +++ b/docs/docs/run_minder_server/config_provider.md @@ -1,10 +1,8 @@ --- -title: Configure a Provider -sidebar_position: 20 +title: Configure a provider +sidebar_position: 50 --- -# Configuring a Provider - A provider connects Minder to your software supply chain — giving Minder information about your source code repositories, and their pull requests, dependencies, and artifacts. @@ -13,7 +11,7 @@ The currently supported providers are: - GitHub -For GitHub, you configure a Provider by creating a GitHub App. +For GitHub, you configure a provider by creating a GitHub App. ## Prerequisites @@ -32,7 +30,7 @@ Minder can access. ![Adding a new GitHub App](./images/new-github-app.png) -### Basic Information +### Basic information Complete the following fields: @@ -46,12 +44,12 @@ Complete the following fields: Complete the following fields: - Callback URL: `http://localhost:8080/api/v1/auth/callback/github-app/app` -- Add an additional Callback URL for Keycloak: +- Add an additional callback URL for Keycloak: `http://localhost:8081/realms/stacklok/broker/github/endpoint` - Select the checkbox for "Request user authorization (OAuth) during installation" -![Configuring the GitHub Provider](./images/provider-ident-and-auth.png) +![Configuring the GitHub provider](./images/provider-ident-and-auth.png) ### Webhook @@ -80,7 +78,7 @@ screenshot. ![Permissions](./images/provider-permissions.png) -### Installation and Scope +### Installation and scope For the option "Where can this GitHub App be installed?": @@ -142,7 +140,7 @@ Update the `client_id` and `client_secret` values with the following: - Client Secret : The value you saved previously. -### Add Provider configuration +### Add provider configuration Then, find the following section in the same `server-config.yaml` file: @@ -177,5 +175,5 @@ Update the `user_id` value with the `id` value returned from that command. ![User ID](./images/provider-user-id.png) -Now save the file. Your Provider is now created and the Minder server is +Now save the file. Your provider is now created and the Minder server is configured to use it. diff --git a/docs/docs/run_minder_server/config_webhook.md b/docs/docs/run_minder_server/config_webhook.md index 26545e0e59..a6632111ba 100644 --- a/docs/docs/run_minder_server/config_webhook.md +++ b/docs/docs/run_minder_server/config_webhook.md @@ -1,10 +1,8 @@ --- -title: Configuring a Webhook -sidebar_position: 70 +title: Configuring a webhook +sidebar_position: 60 --- -# Configuring a Webhook - Minder allows a webhook to be configured on the repository provider to respond to provider events. Currently, Minder only supports GitHub. The webhook allows GitHub to notify Minder when certain events occur in your repositories. To diff --git a/docs/docs/run_minder_server/installing_minder.md b/docs/docs/run_minder_server/installing_minder.md index 68fedcceff..11c69b99f1 100644 --- a/docs/docs/run_minder_server/installing_minder.md +++ b/docs/docs/run_minder_server/installing_minder.md @@ -1,11 +1,10 @@ --- -sidebar_label: Installing a Production version -sidebar_position: 80 +title: Installing Minder with Helm +sidebar_label: Installing a production version +sidebar_position: 20 --- -# Installing Minder with Helm - -## Keycloak Installation +## Keycloak installation Minder is designed to operate without storing user credentials or personal information. To achieve this, it relies on an external identity provider. While @@ -13,12 +12,12 @@ Minder is compatible with any OpenID Connect (OIDC)-enabled identity provider, we have thoroughly tested it with Keycloak and thus recommend it for a seamless integration. -### Getting Started with Keycloak +### Getting started with Keycloak To install Keycloak as your identity provider, please refer to the following resources for detailed instructions: -- Keycloak Operator Installation Guide: +- Keycloak Operator Installation guide: [Keycloak Operator Installation](https://www.keycloak.org/operator/installation) - Keycloak Tutorials for Beginners: [Keycloak Tutorials](https://keycloak.ch/keycloak-tutorials/tutorial-1-installing-and-running-keycloak/) @@ -26,23 +25,23 @@ resources for detailed instructions: After the installation of Keycloak, there are specific settings and configurations required for Minder to function properly: -1. **Realm Configuration:** Set up a dedicated realm in Keycloak for Minder's +1. **Realm configuration:** Set up a dedicated realm in Keycloak for Minder's use. -2. **Client Setup:** Create two separate clients within the realm: +2. **Client setup:** Create two separate clients within the realm: - **minder-cli:** A client for command-line interactions. - **minder-server:** A client for server-side operations. -3. Identity Provider Linkage: Connect your chosen Identity Provider (e.g., +3. Identity provider linkage: Connect your chosen identity orovider (e.g., GitHub, Google) to Keycloak. To facilitate this process, you may use the initialization script available at [Minder Identity Initialization Script](https://github.com/mindersec/minder/blob/main/identity/scripts/initialize.sh). -## Postgres Installation +## PostgreSQL installation -Minder requires a dedicated Postgres database to store its operational data. The -database must have a dedicated user with the necessary privileges and +Minder requires a dedicated PostgreSQL database to store its operational data. +The database must have a dedicated user with the necessary privileges and credentials. -### Best Practices for Database Deployment +### Best practices for database deployment It is recommended to use two distinct database users: @@ -50,9 +49,9 @@ It is recommended to use two distinct database users: - Another solely for database migrations. You can find our database migration scripts at -[Minder Database Migrations](https://github.com/mindersec/minder/tree/main/database/migrations). +[Minder database migrations](https://github.com/mindersec/minder/tree/main/database/migrations). -## Ingress Configuration +## Ingress configuration Your ingress controller must be capable of handling both gRPC and HTTP/1 protocols. @@ -62,7 +61,7 @@ enables ingress for both protocols. If your ingress solution requires different settings, please disable the default ingress in the Helm chart and configure it manually to meet your environment's needs. -## GitHub OAuth Application +## GitHub OAuth application For Minder to interact with GitHub repositories, a GitHub OAuth2 application is required. This is essential for Minder's operation, as it will use this @@ -72,14 +71,14 @@ Please ensure the following secrets are securely stored and handled, as they contain sensitive information crucial for the authentication and operation of Minder's integrations: -- **minder-identity-secrets:** a secret with the key identity_client_secret and - the value being the keycloak minder-server client secret. -- **minder-auth-secrets:** a secret with the key token_key_passphrase and unique - content, used to encrypt tokens in the database. -- **minder-github-secrets:** a secret with the keys client_id and client_secret - that contains the GitHub OAuth app secrets. +- **`minder-identity-secrets`:** a secret with the key identity_client_secret + and the value being the keycloak minder-server client secret. +- **`minder-auth-secrets`:** a secret with the key token_key_passphrase and + unique content, used to encrypt tokens in the database. +- **`minder-github-secrets`:** a secret with the keys client_id and + client_secret that contains the GitHub OAuth app secrets. -## Helm Chart Parameters +## Helm chart parameters ### Minder diff --git a/docs/docs/run_minder_server/intro_to_install.md b/docs/docs/run_minder_server/intro_to_install.md index 6e04c8dddd..bffd8a2ffa 100644 --- a/docs/docs/run_minder_server/intro_to_install.md +++ b/docs/docs/run_minder_server/intro_to_install.md @@ -3,8 +3,6 @@ title: Introduction to running Minder sidebar_position: 5 --- -# Introduction to running Minder - Minder is platform, comprising of a control plane, a CLI, a database and an identity provider. diff --git a/docs/docs/run_minder_server/run_the_server.md b/docs/docs/run_minder_server/run_the_server.md index 641d3f2c53..c145149a07 100644 --- a/docs/docs/run_minder_server/run_the_server.md +++ b/docs/docs/run_minder_server/run_the_server.md @@ -1,10 +1,8 @@ --- -title: Installing a Development version +title: Installing a development version sidebar_position: 10 --- -# Installing a Development version - This guide shows you how to run a Minder server locally. It is intended for users who would like to contribute to the Minder project. It is not intended for production use. This guide will walk you through how to: @@ -12,7 +10,7 @@ production use. This guide will walk you through how to: - Retrieve the latest source code - Set up your development environment - Run the dependent applications -- Create a Provider +- Create a provider - Set up authentication Once you complete this guide, you will have a Minder server built from source @@ -37,7 +35,7 @@ git clone git@github.com:mindersec/minder.git cd minder ``` -### Set up Development Environment +### Set up development environment To set up your development environment, run: @@ -61,13 +59,13 @@ make build You may copy these into a location on your path, or run them directly from the `bin` directory. -### Configure the Repository Provider +### Configure the repository provider -You now need to create a Provider to enable Minder to inspect and manage your -repository configuration. Currently only GitHub is supported as a Provider, so +You now need to create a provider to enable Minder to inspect and manage your +repository configuration. Currently only GitHub is supported as a provider, so we'll do this using a GitHub App. This app will also provide Keycloak with an authentication source. Follow the steps in -[Configuring a Provider](./config_provider.md) then return here to complete +[Configuring a provider](./config_provider.md) then return here to complete configuring the server. Be sure to save the Client ID and Client secret values, because you will need them again below. @@ -116,7 +114,7 @@ make KC_GITHUB_CLIENT_ID= KC_GITHUB_CLIENT_SECRET= git You should see it create a new instance and new mappers. You may see a resource not found message. This is safe to ignore. -### Authenticate minder +### Authenticate Minder CLI At this point, you should have the following: @@ -133,38 +131,38 @@ minder auth login This will open Keycloak login window in your browser. -![Keycloak Login](./images/keycloak-login.png) +![Keycloak login](./images/keycloak-login.png) Click GitHub to sign in. This should display a GitHub authorization window asking if you'd like to give permission to your Minder server. -![Github Auth](./images/github-auth.png) +![GitHub auth](./images/github-auth.png) Click Authorize. The browser window should say Authentication Successful and the command line should say you've been successfully registered. -![Successful Minder Auth](./images/successful-install.png) +![Successful Minder auth](./images/successful-install.png) Congratulations! You've set up a Minder server! Now you're all ready to contribute to Minder. For more information about the development process, please see the -[Developer Guide](https://minder-docs.stacklok.dev/developer_guide/get-hacking). +[Developer guide](https://minder-docs.stacklok.dev/developer_guide/get-hacking). For more information on contributing, please see our -[Contributing Guide](https://github.com/mindersec/minder/blob/main/CONTRIBUTING.md). +[Contributing guide](https://github.com/mindersec/minder/blob/main/CONTRIBUTING.md). A list of good first issues can be found in the [Minder GitHub project](https://github.com/mindersec/minder/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22). -## Optional Steps +## Optional steps -### Setting up a Webhook +### Setting up a webhook With the basic setup, GitHub is unable to notify Minder when certain events occur in your repositories. MORE DETAILS WOULD BE NICE. Configuring a Webhook will allow GitHub to communicate back to the Minder instance. Details on how to -set this up can be found in the [Configuring a Webhook](./config_webhook.md) +set this up can be found in the [Configuring a webhook](./config_webhook.md) guide. ### Running Minder server directly @@ -182,7 +180,7 @@ running. docker stop minder_server ``` -#### Configuration Changes +#### Configuration changes Find the authz section in your `server-config.yaml` file located in your root Minder directory. Update the `api_url` to point to `http://localhost:8082`. diff --git a/docs/docs/understand/alerts.md b/docs/docs/understand/alerts.md index 9cc267131a..9e5814448f 100644 --- a/docs/docs/understand/alerts.md +++ b/docs/docs/understand/alerts.md @@ -3,8 +3,6 @@ title: Alerting sidebar_position: 60 --- -# Alerts from Minder - Minder issues _alerts_ to notify you when the state of your software supply chain does not meet the criteria that you've defined in your [profile](profiles.md). @@ -26,7 +24,7 @@ In the alert, you'll be able to see details such as: - Severity of the issue. The severity of the alert is based on what is set in the rule type definition. -### Enabling alerts in a profile +## Enabling alerts in a profile To activate the alert feature within a profile, you need to adjust the YAML definition. Specifically, you should set the alert parameter to "on": diff --git a/docs/docs/understand/profiles.md b/docs/docs/understand/profiles.md index 191f07dea2..ab1e436d86 100644 --- a/docs/docs/understand/profiles.md +++ b/docs/docs/understand/profiles.md @@ -1,10 +1,8 @@ --- -title: Profiles and Rules +title: Profiles and rules sidebar_position: 10 --- -# Profiles in Minder - A _profile_ defines your security policies that you want to apply to your software supply chain. Profiles contain rules that query data in a [provider](providers.md), and specifies whether Minder will issue @@ -29,8 +27,8 @@ Each engine is designed to be extensible, allowing you to integrate your own logic and processes. Stacklok has published -[a set of example profiles on GitHub](https://github.com/mindersec/minder-rules-and-profiles/tree/main/profiles/github); -see [Managing Profiles](../how-to/manage_profiles.md) for more details on how to +[a set of example profiles on GitHub](https://github.com/mindersec/minder-rules-and-profiles/tree/main/profiles); +see [Managing profiles](../how-to/manage_profiles.md) for more details on how to set up profiles and rule types. ## Rules @@ -65,7 +63,7 @@ def: ``` You can find a list of available rules in the -[https://github.com/mindersec/minder-rules-and-profiles](https://github.com/mindersec/minder-rules-and-profiles/tree/main/rule-types/github) +[https://github.com/mindersec/minder-rules-and-profiles](https://github.com/mindersec/minder-rules-and-profiles/tree/main/rule-types) repository. ## Actions diff --git a/docs/docs/understand/projects.md b/docs/docs/understand/projects.md index c85f743f1c..7cbecadc81 100644 --- a/docs/docs/understand/projects.md +++ b/docs/docs/understand/projects.md @@ -3,8 +3,6 @@ title: Projects sidebar_position: 20 --- -# Projects in Minder - Projects in Minder are a way to group entities together, and to share access with other people in your organization. They are a way to organize your entities (repositories, artifacts, etc.) based on the policy you want to enforce or the diff --git a/docs/docs/understand/providers.md b/docs/docs/understand/providers.md index cb54c1d25e..8b94a366a5 100644 --- a/docs/docs/understand/providers.md +++ b/docs/docs/understand/providers.md @@ -3,8 +3,6 @@ title: Providers sidebar_position: 20 --- -# Providers in Minder - A _provider_ connects Minder to your software supply chain — giving Minder information about your source code repositories, and their pull requests, dependencies, and artifacts. Minder will apply your [profiles](profiles.md) to @@ -22,7 +20,7 @@ Stay tuned as we add more providers in the future! To enroll GitHub as a provider, use the following command: -``` +```bash minder provider enroll ``` diff --git a/docs/docs/understand/remediations.md b/docs/docs/understand/remediations.md index 751e690e73..f075e54036 100644 --- a/docs/docs/understand/remediations.md +++ b/docs/docs/understand/remediations.md @@ -1,10 +1,8 @@ --- -title: Automatic remediations +title: Automatic remediation sidebar_position: 70 --- -# Automatic Remediations in Minder - Minder can perform _automatic remediation_ for many rules in an attempt to resolve problems in your software supply chain, and bring your resources into compliance with your [profile](profiles.md). @@ -18,7 +16,7 @@ Scanning should be enabled, and you have enabled automatic remediation in your profile, then Minder will attempt to turn Secret Scanning on in any repositories where it is not enabled. -### Enabling remediations in a profile +## Enabling remediations in a profile To activate the remediation feature within a profile, you need to adjust the YAML definition. Specifically, you should set the remediate parameter to "on": diff --git a/docs/docs/understand/repository_registration.md b/docs/docs/understand/repository_registration.md index 30da2c2d97..377c858e40 100644 --- a/docs/docs/understand/repository_registration.md +++ b/docs/docs/understand/repository_registration.md @@ -11,7 +11,7 @@ when the repository is out of compliance. ## Registering repositories -Once you have [enrolled the GitHub Provider](providers.md), you can register +Once you have [enrolled the GitHub provider](providers.md), you can register repositories that you granted Minder access to within GitHub. To get a list of repositories, and select them using a menu in Minder's text @@ -38,11 +38,11 @@ to your repositories and re-scan them for compliance with your profiles. ## Automatically registering new repositories -The GitHub Provider can be configured to automatically register new repositories +The GitHub provider can be configured to automatically register new repositories that are created in your organization. This is done by setting an attribute on the provider. -First, identify the _name_ of your GitHub Provider. You can list your enrolled +First, identify the _name_ of your GitHub provider. You can list your enrolled providers by running: ```bash @@ -75,10 +75,14 @@ To disable automatic registration, set the minder provider update --set-attribute=auto_registration.entities.repository.enabled=false --name=github-app-myorg ``` -:::note Disabling automatic registration will not remove the repositories that -have already been registered. ::: +:::note -## List and get Repositories +Disabling automatic registration will not remove the repositories that have +already been registered. + +::: + +## List and get repositories You can list all repositories registered in Minder: diff --git a/docs/docs/understand/rule_evaluation.md b/docs/docs/understand/rule_evaluation.md index 427c2355e8..ea452d8145 100644 --- a/docs/docs/understand/rule_evaluation.md +++ b/docs/docs/understand/rule_evaluation.md @@ -3,8 +3,6 @@ title: Rule evaluations sidebar_position: 50 --- -# Rule evaluations - When Minder evaluates the [rules in your profiles](profiles.md), it records the state of those evaluations. When those rules are not satisfied because the criteria that you defined was not met, it will issue [alerts](alerts.md). @@ -25,13 +23,13 @@ In a rule evaluation, you'll see: - Whether [automatic remediation](remediations.md) was performed, and if so, its status -### Viewing rule evaluations +## Viewing rule evaluations To view the rule evaluations, run [`minder history list`](../ref/cli/minder_history_list.md). You can query the history to only look at certain entities, profiles, or statuses. -### Evaluation status +## Evaluation status The _status_ of a rule evaluation describes the outcome of executing the rule against an entity. Possible statuses are: @@ -51,7 +49,7 @@ against an entity. Possible statuses are: [`secret_scanning`](../ref/rules/secret_scanning.md) rule, it can be configured to skip private repositories. -### Alert status +## Alert status When a rule evaluation occurs, an [alert](alerts.md) may be created. Each rule evaluation has an alert status: @@ -62,7 +60,7 @@ evaluation has an alert status: - **Skipped**: the rule evaluation was successful, meaning an alert should not be created, or the profile is not configured to generate alerts -### Remediation status +## Remediation status - **Success**: the issue was automatically remediated - **Failure**: the issue could not be automatically remediated diff --git a/docs/docs/user_management/adding_users.md b/docs/docs/user_management/adding_users.md index 378e66bd9b..08f73423d6 100644 --- a/docs/docs/user_management/adding_users.md +++ b/docs/docs/user_management/adding_users.md @@ -1,5 +1,5 @@ --- -title: Adding Users to your Project +title: Adding users to your project sidebar_position: 100 --- @@ -24,7 +24,7 @@ appropriate role based on their responsibilities and required access levels. Roles are [documented here](user_roles.md). To view the available roles in your project, and their descriptions, run: -``` +```bash minder project role list ``` @@ -56,7 +56,7 @@ To add a user to your project, follow these steps: used with [`minder auth invite accept`](../ref/cli/minder_auth_invite_accept.md). -## Have the User Exercise the Invitation Code +## Have the user exercise the invitation code Relay the invitation code to the user who you are inviting to join your project. They will need to install the `minder` CLI and run @@ -73,7 +73,7 @@ by executing: minder project role grant list ``` -## Working with Multiple Projects +## Working with multiple projects When you have access to more than one project, you will need to qualify many `minder` commands with which project you want them to apply to. You can either @@ -82,7 +82,7 @@ use the `--project` flag, set a default in your environment variable. To see all the projects that are available to you, use the [`minder project list`](../ref/cli/minder_project_list.md) command. -``` +```plain +--------------------------------------+-------------------+ | ID | NAME | +--------------------------------------+-------------------+ diff --git a/docs/docs/user_management/user_roles.md b/docs/docs/user_management/user_roles.md index c944eface2..ed40a00db9 100644 --- a/docs/docs/user_management/user_roles.md +++ b/docs/docs/user_management/user_roles.md @@ -1,4 +1,7 @@ -# User roles in Minder +--- +title: User roles +sidebar_position: 110 +--- When incorporating a user into your project, it's crucial to assign them the appropriate role based on their responsibilities and required access levels. diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index cdf8892e9f..244b521da4 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -151,7 +151,7 @@ const config = { }, ], copyright: `Copyright © ${new Date().getFullYear()} Minder a Series of LF Projects, LLC -For web site terms of use, trademark policy and other project policies please see https://lfprojects.org.. Built with Docusaurus.`, +For web site terms of use, trademark policy and other project policies please see https://lfprojects.org.`, }, prism: { theme: lightCodeTheme, From f9be8c37d9266f28861b0188af734b247fbcc875 Mon Sep 17 00:00:00 2001 From: Dan Barr Date: Thu, 9 Jan 2025 20:40:04 -0500 Subject: [PATCH 3/4] Delete unused scaffolding files --- docs/src/pages/index.module.css | 28 ---------------------------- docs/src/pages/markdown-page.md | 7 ------- 2 files changed, 35 deletions(-) delete mode 100644 docs/src/pages/index.module.css delete mode 100644 docs/src/pages/markdown-page.md diff --git a/docs/src/pages/index.module.css b/docs/src/pages/index.module.css deleted file mode 100644 index d7d5ed4b33..0000000000 --- a/docs/src/pages/index.module.css +++ /dev/null @@ -1,28 +0,0 @@ -/* - SPDX-FileCopyrightText: Copyright YYYY The Minder Authors - SPDX-License-Identifier: Apache-2.0 -*/ - -/** - * CSS files with the .module.css suffix will be treated as CSS modules - * and scoped locally. - */ - -.heroBanner { - padding: 4rem 0; - text-align: center; - position: relative; - overflow: hidden; -} - -@media screen and (max-width: 996px) { - .heroBanner { - padding: 2rem; - } -} - -.buttons { - display: flex; - align-items: center; - justify-content: center; -} diff --git a/docs/src/pages/markdown-page.md b/docs/src/pages/markdown-page.md deleted file mode 100644 index 9756c5b668..0000000000 --- a/docs/src/pages/markdown-page.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Markdown page example ---- - -# Markdown page example - -You don't need React to write simple standalone pages. From 761d3e0761e6351685b37b28c66eaf03779a85cf Mon Sep 17 00:00:00 2001 From: Dan Barr Date: Sat, 18 Jan 2025 01:00:30 -0500 Subject: [PATCH 4/4] Update docs README --- docs/README.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/docs/README.md b/docs/README.md index 60f0f4c70c..37393179da 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,8 +3,8 @@ This directory contains the user documentation for Minder, hosted at . -The docs are built with [Docusaurus](<[https://](https://docusaurus.io/)>), an -open source static website generator optimized for documentation use cases. +The docs are built with [Docusaurus](https://docusaurus.io/), an open source +static website generator optimized for documentation use cases. ## Contributing to docs @@ -24,7 +24,14 @@ CLI docs: make cli-docs ``` -Run a preview server: +Change to the docs directory: + +```bash +cd docs +``` + +Run a preview server (this will automatically refresh most changes as you make +them): ```bash npm run start @@ -32,20 +39,19 @@ npm run start Your browser should automatically open to -Build the docs: +Run a "production" build, this will also test for broken internal links: ```bash -cd docs npm run build ``` -Serve the docs +Serve the production build locally: ```bash npm run serve -- --port 3001 ``` -Visit http://localhost:3001/ to view the docs. +Visit http://localhost:3001/ to view the build. ## Formatting