Creating a profile

In this howto we'll create a Minder profile that checks whether secret scanning and dependabot for Python are enabled in a repository.

Prerequisites

• The minder CLI application
• A Stacklok account - create one by logging into the hosted minder instance or by running minder auth login from the command line
• A GitHub repository to be enrolled by Minder

Create a profile from the UI

Start by enrolling a repository unless you've already done so. Select "Repositories" in the left sidebar, then "Add Repository". Follow the wizard and register at least one repository.

To create a profile, select "Profiles" in the left sidebar, then "New Profile". The wizard presents a selection of Stacklok-curated profiles, but in this case we'll want to create one with our selection of rules. Select "Create Custom Profile" and provide a name for the profile.

In the "Add rule" dialog, we'll add the first rule to the profile. Find the rule called "secret_scanning". In the right sidebar that opens, select both the "Enabled" and "skip_private_repos" checkboxes and then select "Add rule".

Repeat the "Add rule" process for the dependabot rule. Use "requirements.txt", "pypi" and "daily" for the values of the apply_if_file, package_ecosystem and schedule_interval respectively.

Now that your profile has been created, you should be able to navigate back to the "Repositories" section in the left sidebar and see the profile applied to all repositories you registered as well as an overview of the issues that the profiles found.

Create a profile from the command line

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.

version: v1
type: profile
name: my-first-profile
context:
  provider: github

Turn on alerting, so that a security advisory will be created for any registered repository that has not enabled secret scanning.

alert: "on"

Turn on remediation, so that secret scanning will automatically be enabled for any registered repositories.

remediate: "on"

Create the secret scanning rule:

repository:
  - type: secret_scanning
    def:
      enabled: true

Next, add the dependabot rule:

repository:
  - type: dependabot_configured
    def:
      package_ecosystem: pypi
      schedule_interval: weekly
      apply_if_file: requirements.txt

Putting it all together, you get the following content if profile.yaml:

version: v1
type: profile
name: my-first-profile
context:
  provider: github
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
    def:
      enabled: true
  - type: dependabot_configured
    def:
      package_ecosystem: pypi
      schedule_interval: weekly
      apply_if_file: requirements.txt

Finally, create your profile in Minder:

minder profile create -f profile.yaml

Check the status of your profile and see which repositories satisfy the rules by running:

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:

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.

List rule types

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.

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.

repository:
  - type: secret_scanning
    name: "secret_scanning_github"
    def:
      enabled: true

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.

repository:
  - type: secret_scanning
    name: "secret_scanning_github"
    def:
      enabled: true
  - type: secret_scanning
    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.

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.

repository: # Would return an error while creating
  - type: secret_scanning
    name: "protect_github"
    def:
      enabled: true
  - type: secret_push_protection
    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:

repository: # Would return an error while creating
  - type: dependabot_configured
    name: "dependabot_configured"
    def:
      package_ecosystem: gomod
      schedule_interval: daily
      apply_if_file: go.mod
  - type: dependabot_configured # default 'name' would be 'dependabot_configured'
    def:
      package_ecosystem: npm
      schedule_interval: daily
      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.

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.

repository:
  - type: dependabot_configured
    name: "Dependabot Configured for GoLang"
    def:
      package_ecosystem: gomod
      schedule_interval: daily
      apply_if_file: go.mod
  - type: dependabot_configured # default 'name' would be 'dependabot_configured'
    def:
      package_ecosystem: npm
      schedule_interval: daily
      apply_if_file: docs/package.json

You can find the rule definitions used above and many profile examples at minder-rules-and-profiles repository.