From 26a64394c6f268cdfbd1038245b0f69bba05325f Mon Sep 17 00:00:00 2001 From: Edward Thomson Date: Thu, 24 Oct 2024 14:58:27 +0100 Subject: [PATCH 1/2] Update `mindev` README with `ruletype test` details Add additional details to the `mindev` README for using `ruletype test`. --- cmd/dev/README.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/cmd/dev/README.md b/cmd/dev/README.md index e597ec0f1e..7b353f9efb 100644 --- a/cmd/dev/README.md +++ b/cmd/dev/README.md @@ -20,7 +20,7 @@ mindev [command] ### Testing a rule type ```bash -mindev ruletype test -e /path/to/entity -p /path/to/profile -r /path/to/rule +mindev ruletype test -e /path/to/entity -p /path/to/profile -r /path/to/ruletype ``` `ruletype test` is intended for testing a single rule; the entity definition @@ -36,13 +36,26 @@ github/repo_name: my-repo github/repo_owner: my-org github/repo_id: 123456789 github/clone_url: https://github.com/my-org/my-repo.git +is_private: false +is_fork: false ``` +You can see complete entity schema in the [`examples`](https://github.com/mindersec/minder/tree/main/cmd/dev/examples) folder. + The profile is the path to the profile file. This is needed to test the rule since rules often take definitions and parameters from the profile. Note that the profile must instantiate the rule type you're testing. -Finally, the rule type is the path to the rule type file. +The rule type is the path to the rule type file. + +Finally, you will need to specify an auth token that can evaluate the +rule type, using the `TEST_AUTH_TOKEN` environment variable. 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 +``` ### Linting a rule type From f4d3ec1962b07705ae246779731a298f9323cfc5 Mon Sep 17 00:00:00 2001 From: Edward Thomson Date: Thu, 24 Oct 2024 15:14:37 +0100 Subject: [PATCH 2/2] Update docs with links to mindev entity examples --- docs/docs/how-to/mindev.md | 52 +++++++++++++++++++++++++++++--------- 1 file changed, 40 insertions(+), 12 deletions(-) diff --git a/docs/docs/how-to/mindev.md b/docs/docs/how-to/mindev.md index 0737cbce34..05c9f5ce68 100644 --- a/docs/docs/how-to/mindev.md +++ b/docs/docs/how-to/mindev.md @@ -33,14 +33,28 @@ mindev ruletype help ## Linting -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 -f path/to/rule-type.yaml ``` +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. + +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: ```bash @@ -68,21 +82,33 @@ The values needed must match an entity's protobuf definition. for instance, for ```yaml --- -name: -owner: -repo_id: -clone_url: -default_branch: +github/repo_name: +github/repo_owner: +github/repo_id: +github/clone_url: +github/default_branch: +is_private: +is_fork: ``` 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. + ## Authentication If the rule type requires authentication, you can use the following environment variable: ```bash -export AUTH_TOKEN=your_token +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: + +```bash +TEST_AUTH_TOKEN=$(gh auth token) mindev ruletype test -e /path/to/entity -p /path/to/profile -r /path/to/rule ``` ### Example @@ -95,11 +121,13 @@ We'll create a file called `entity.yaml` with the following content: ```yaml --- -name: minder -owner: stacklok -repo_id: 624056558 -clone_url: https://github.com/mindersec/minder.git -default_branch: main +github/repo_name: minder +github/repo_owner: stacklok +github/repo_id: 624056558 +github/clone_url: https://github.com/mindersec/minder.git +github/default_branch: main +is_private: false +is_fork: false ``` We'll use the readily available profile for dependabot for golang dependencies: