https://github.com/mindersec/minder
Software Supply Chain Security Platform
https://github.com/mindersec/minder
security software-supply-chain software-supply-chain-security supply-chain
Last synced: 9 days ago
JSON representation
Software Supply Chain Security Platform
- Host: GitHub
- URL: https://github.com/mindersec/minder
- Owner: mindersec
- License: apache-2.0
- Created: 2023-04-05T16:47:15.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2026-01-13T16:40:14.000Z (11 days ago)
- Last Synced: 2026-01-13T18:26:51.329Z (11 days ago)
- Topics: security, software-supply-chain, software-supply-chain-security, supply-chain
- Language: Go
- Homepage: https://mindersec.dev/
- Size: 139 MB
- Stars: 369
- Watchers: 17
- Forks: 53
- Open Issues: 111
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Maintainers: MAINTAINERS.md
Awesome Lists containing this project
README
[](https://github.com/mindersec/minder/actions/workflows/main.yml) | [](https://coveralls.io/github/mindersec/minder?branch=main) | [](https://opensource.org/licenses/Apache-2.0) | [](https://slsa.dev) | [](https://discord.gg/RkzVuTp3WK)
---
[Installation](https://mindersec.github.io/getting_started/install_cli) | [Documentation](https://mindersec.github.io/) | [Releases](https://github.com/mindersec/minder/releases)
---
# 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 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 consumers.
Minder allows users to enroll repositories and define policy to ensure repositories and artifacts are configured
consistently and securely. Policies can be set to alert only or auto-remediate. Minder provides a predefined set of
rules and can also be configured to apply custom rules.
Minder can be deployed as a Helm chart and provides a CLI tool `minder`. Custcodian also
provides a [free-to-use hosted version of Minder](#public-instance). Minder is designed to be extensible,
allowing users to integrate with their existing tooling and processes.
## Features
* **Repo configuration and security:** Simplify configuration and management of security settings and policies across repos.
* **Proactive security enforcement:** Continuously enforce best practice security configurations by setting granular policies to alert only or auto-remediate.
* **Artifact attestation:** Continuously verify that packages are signed to ensure they’re tamper-proof, using the open source project Sigstore.
* **Dependency management:** Manage dependency security posture by helping developers make better choices and enforcing controls. Minder is integrated with [OSV](https://osv.dev/) (and can be integrated with other SCA APIs) to enable policy-driven dependency management based on the risk level of dependencies.
## Public Instance
Custcodian [provides a free-to-use public instance of Minder](https://custcodian.dev/hosted/) at `api.custcodian.dev`. This is the default instance used when you use the `minder` CLI starting with release 0.0.89. This instance is free to use for public repositories; for private repositories, there may be an additional charge for using this cloud-hosted instance.
---
# Getting Started (< 1 minute)
Getting up and running with Minder takes under a minute and is as easy as:
1. Installing Minder
2. Logging in to Minder
3. and running `minder quickstart` to create your first profile.
In just a few seconds, you will register your repositories and enable secret scanning protection for all of them! 🤯
## Installation
Choose your preferred method to install `minder`:
### MacOS (Homebrew)
Make sure you have [Homebrew](https://brew.sh/) installed.
```bash
brew install minder
```
### Windows (Winget)
Make sure you have [Winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/) installed.
```bash
winget install mindersec.minder
```
### Download a release
Download the latest release from [minder/releases](https://github.com/mindersec/minder/releases).
### Build it from source
Build `minder` and `minder-server` from source by following the [build from source guide](#build-from-source).
## Logging in to Minder
To use `minder` with the [public instance](#public-instance) of Minder (`api.custcodian.dev`), log in by running:
```bash
minder auth login --grpc-host api.custcodian.dev
```
(This API host is the default starting with the 0.0.89 release.) Upon completion, you should see that the Minder Server is set to `api.custcodian.dev`.
## Run Minder quickstart
The `quickstart` command guides you through creating your first profile in Minder, register your repositories, and enabling secret scanning protection for your repositories in seconds.
To do so, run:
```bash
minder quickstart
```
This will prompt you to enroll your provider, select the repositories you'd like, create the `secret_scanning`
rule type and create a profile which enables secret scanning for the selected repositories.
To see the status of your profile, run:
```bash
minder profile status list --profile quickstart-profile --detailed
```
You should see the overall profile status and a detailed view of the rule evaluation statuses for each of your registered repositories.
Minder will continue to keep track of your repositories and will ensure to fix any drifts from the desired state by
using the `remediate` feature or alert you, if needed, using the `alert` feature.
Congratulations! 🎉 You've now successfully created your first profile!
## What's next?
You can now continue to explore Minder's features by adding or removing more repositories, create more profiles with
various rules, and much more. There's a lot more to Minder than just secret scanning.
The `secret_scanning` rule is just one of the many rule types that Minder supports.
You can see the full list of ready-to-use rules and profiles
maintained by Minder's team here - [mindersec/minder-rules-and-profiles](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.
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.
For more information about `minder`, see:
* `minder` CLI commands - [Docs](https://mindersec.github.io/ref/cli/minder).
* `minder` REST API Documentation - [Docs](https://mindersec.github.io/ref/api).
* `minder` rules and profiles maintained by Minder's team - [GitHub](https://github.com/mindersec/minder-rules-and-profiles).
* Minder documentation - [Docs](https://mindersec.github.io/).
# Roadmap
The Minder community are actively working on new features and improvements for Minder.
You can find our roadmap [here](https://mindersec.github.io/about/roadmap).
Should you wish to request or contribute a feature or improvement, please use the following
[issue template](https://github.com/mindersec/minder/issues/new?template=enhancement.yml)
# Development
This section describes how to build and run Minder from source.
## Build from source
### Prerequisites
You'd need the following tools available - [Go](https://golang.org/doc/install), [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/).
To build and run `minder-server`, you will also need [ko](https://ko.build/install/).
To run the test suite via `make test`, you will need [gotestfmt](https://github.com/GoTestTools/gotestfmt#installing) and [helm](https://github.com/helm/helm/releases).
To invoke the `run-docker` make target, you will need [yq](https://github.com/mikefarah/yq).
### Clone the repository
```bash
git clone git@github.com:mindersec/minder.git
```
## Build
Run the following to build `minder` and `minder-server` (binaries will be present at `./bin/`)
```bash
make build
```
To use `minder` with the public instance of Minder (`api.custcodian.dev`), run:
```bash
minder auth login --grpc-host api.custcodian.dev
```
Upon completion, you should see that the Minder Server is set to `api.custcodian.dev`.
If you want to run `minder` against a local `minder-server` instance, you can use the `--grpc-host=localhost` and `--grpc-port=8090` flags, or use a configuration file following the steps below.
#### Initial configuration
Create the initial configuration file for `minder`. You may do so by doing.
```bash
cp config/config.yaml.example config.yaml
```
Create the initial configuration file for `minder-server`. You may do so by doing:
```bash
cp config/server-config.yaml.example server-config.yaml
```
You also have to set up an OAuth2 application for `minder-server` to use.
Once completed, update the configuration file with the appropriate values.
See the documentation on how to do that - [Docs](https://mindersec.github.io/run_minder_server/config_oauth).
#### Run `minder-server`
Start `minder-server` along with its dependant services (`keycloak` and `postgres`) by running:
```bash
make run-docker
```
#### Configure social login (GitHub)
`minder-server` uses Keycloak as an IAM. To log in, you'll need to set up a GitHub OAuth2 application and configure
Keycloak to use it.
Create an OAuth2 application for GitHub [here](https://github.com/settings/developers). Select
`New OAuth App` and fill in the details. The callback URL should be `http://localhost:8081/realms/stacklok/broker/github/endpoint`.
Create a new client secret for your OAuth2 client.
Using the `client_id` and `client_secret` you created above, enable GitHub login on Keycloak by running the following command:
```bash
make KC_GITHUB_CLIENT_ID= KC_GITHUB_CLIENT_SECRET= github-login
```
#### Run minder
Ensure the `config.yaml` file is present in the current directory so `minder` can use it.
Run `minder` against your local instance of Minder (`localhost:8090`):
```bash
minder auth login
```
Upon completion, you should see that the Minder Server is set to `localhost:8090`.
By default, the `minder` CLI will point to the Custcodian cloud environment if a config file is not present, but [creating the `config.yaml` for running the server](#initial-configuration) will point the CLI at your local development environment. If you explicitly want to use a different instance, you can set the `MINDER_CONFIG` environment variable to point to a particular configuration. We have configurations for local development and the Custcodian cloud environment checked in to [the `config` directory](./config/).
### Development guidelines
You can find more detailed information about the development process in the [Developer Guide](https://mindersec.github.io/developer_guide/get-hacking).
## Minder API
* REST API documentation - [Link](https://mindersec.github.io/ref/api).
* Proto API documentation - [Link](https://mindersec.github.io/ref/proto).
* Protobuf - [Link](https://github.com/mindersec/minder/blob/main/proto/minder/v1/minder.proto).
* OpenAPI/swagger spec (JSON) - [Link](https://github.com/mindersec/minder/blob/main/pkg/api/openapi/minder/v1/minder.swagger.json).
## Contributing
We welcome contributions to Minder. Please see our [Contributing](./CONTRIBUTING.md) guide for more information.
## Provenance
The Minder project follows the best practices for software supply chain security and transparency.
All released assets:
* Have a generated and verifiable SLSA Build Level 3 provenance. For more information, see the [SLSA website](https://slsa.dev).
* Have been signed and verified during release using the [Sigstore](https://sigstore.dev) project.
This ensures that
they are tamper-proof and can be verified by anyone.
* Have an SBOM archive generated and published along with the release.
This allows users to understand the dependencies of the project and their security posture.
## License
Minder is licensed under the [Apache 2.0 License](./LICENSE).