login docs.md

README.md

@@ -37,23 +37,23 @@ allowing users to integrate with their existing tooling and processes.
 
 You can install `minder` using one of the following methods:
 
-* **Homebrew**
+### MacOS (Homebrew)
 
 ```bash
 brew install stacklok/tap/minder
 ```
 
-* **Winget**
+### Windows (Winget)
 
 ```bash
 winget install stacklok.minder
 ```
 
-* **Releases**
+### Releases
 
 Download the latest release from - [minder/releases](https://github.com/stacklok/minder/releases).
 
-* **Build it from source** 
+### Build it from source
 
 Build `minder` and `minder-server` from source by following - [#build-from-source](#build-from-source).
 

docs/docs/getting_started/install_cli.md

@@ -5,28 +5,41 @@ sidebar_position: 10
 
 # Installing the Minder CLI
 
+Minder consists of two components: a server-side application, and the `minder`
+CLI application for interacting with the server.  Minder is built for `amd64`
+and `arm64` architectures on Windows, MacOS, and Linux.
+
 You can install `minder` using one of the following methods:
 
-* **Homebrew (macOS)**
+## MacOS (Homebrew)
+
+The easiest way to install `minder` is through [Homebrew](https://brew.sh/):
 
 ```bash
 brew install stacklok/tap/minder
 ```
 
-* **Winget (Windows)**
+Alternatively, you can [download a `.tar.gz` release](https://github.com/stacklok/minder/releases) and unpack it with the following:
 
 ```bash
-winget install stacklok.minder
+tar -xzf minder_${RELEASE}_darwin_${ARCH}.tar.gz minder
+xattr -d com.apple.quarantine minder
 ```
 
-* **Releases**
+## Windows (Winget)
+
+For Windows, the built-in `winget` tool is the simplest way to install `minder`:
+
+```bash
+winget install stacklok.minder
+```
 
-Minder is built for the following platforms: `linux`, `darwin`, `windows` and the following
-architectures: `amd64`, `arm64`.
+Alternatively, you can [download a zipfile containing the `minder` CLI](https://github.com/stacklok/minder/releases) and install the binary yourself.
 
-Download the latest releases from - [minder/releases](https://github.com/stacklok/minder/releases).
+## Linux
 
+We provide pre-built static binaries for Linux at: https://github.com/stacklok/minder/releases.
 
-* **Build it from source**
+## Building from source
 
-Build `minder` from source by following - [build-from-source](https://github.com/stacklok/minder#build-from-source).
+You can also build the `minder` CLI from source using `go install github.com/stacklok/minder/cmd/cli@latest`, or by [following the build instructions in the repository](https://github.com/stacklok/minder#build-from-source).

docs/docs/getting_started/login.md

@@ -1,28 +1,79 @@
 ---
-title: Login with Minder
+title: Logging in to Minder
 sidebar_position: 20
 ---
 
+# Logging in and Enrolling a Provider
+
+Minder consists of a client-side CLI tool and a server-side component.  The server-side component runs as a multi-user service.  In order to use Minder to manage repositories and artifacts, you need to log in, which will automatically create an account.
+
 ## Prerequisites
 
-* The `minder` CLI application
+* [The `minder` CLI application](./install_cli.md)
+* A running Minder server, including a running KeyCloak installation
+
+If you don't want to run your own Minder server, Stacklok hosts a public instance.  See [Logging in to the Stacklok-hosted Instance](#logging-in-to-the-stacklok-hosted-instance) below.
 
-## Login as a user
+## Logging in to your own Minder instance
 
-1. Log in with username and password.  By default, `minder` will run against a public Stacklok cloud instance, but this can be changed in `config.yaml` in your local directory or using the `--gprc-host` and `--grpc-port` flags.
+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:
+
+```bash
+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
+
+```
+    You have successfully logged in.
+
+ Here are your details: 
+
+┌────────────────────────────────────────────────┐
+│ Key                    Value                   │
+│ Project Name           KeyCloak-username       │
+│ Minder Server          localhost:8090          │
+└────────────────────────────────────────────────┘
+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](#enrolling-the-github-provider).
+
+## Logging in to the Stacklok-hosted instance
+
+The `minder` CLI defaults to using the hosted Stacklok environment.  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 hosted environment by running:
 
 ```bash
 minder auth login
 ```
 
-A new browser window will open, where you can register a new user and log in.
+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.
+
+## Enrolling the GitHub Provider
 
-Once logged in:
+Once you have authenticated to Minder, you'll want to enroll your GitHub credentials to allow Minder to manage your GitHub repositories.  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.
 
-2. Enroll a user with the given provider
+To enroll your GitHub credentials in your Minder account, run:
 
 ```bash
 minder provider enroll --provider github
 ```
 
-A browser session will open, and you will be prompted to login to your GitHub account. Once you have granted Minder access, you will be redirected back, and the user will be enrolled. The `minder` CLI application will report the session is complete.
+A browser session will open, and you will be prompted to login to your GitHub account.
+
+![Enrollment screenshot](./enroll-screenshot.png)
+
+Once you have granted Minder access, you will be redirected back, and the user will be enrolled. The `minder` CLI application will report the session is complete.
+
+When enrolling an organization, use the `--owner` flag of the `minder provider enroll` command to specify the organization name:
+```bash
+minder provider enroll --provider github --owner test-org
+```
+The `--owner` flag is not required when enrolling repositories from your personal account.
+
+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.

docs/docs/tutorials/remediations.md → docs/docs/getting_started/remediations.md

@@ -1,39 +1,33 @@
 ---
 title: Automatic Remediations
-sidebar_position: 20
+sidebar_position: 70
 ---
 
-## Goal
+# Automatic Remediation with Minder
 
-The goal of this tutorial is to show how Minder can ensure
-that enrolled repos have secret scanning enabled.  Secret scanning is
-one of several settings which can be managed by Minder.  When you
-apply a Minder profile to enrolled repositories, it will remediate (fix)
-the setting if it is changed to violate the profile.
+In [Enabling Secret Scanning](./secret_scanning.md), we wrote a rule to open a
+security advisory when repo configuration drifted from the configured profile
+in Minder.  In this tutorial, we will show how Minder can automatically
+resolve the misconfiguration and ensure that enrolled repos have secret
+scanning enabled.  Secret scanning isone of several settings which can be
+managed by Minder.  When you apply a Minder profile to enrolled repositories,
+it will remediate (fix) the setting if it is changed to violate the profile.
 
 ## Prerequisites
 
-In order to follow the tutorial, ensure that you have completed the tutorial on
-[registering repositories](register_repo_create_profile.md) first.
+* [The `minder` CLI application](./install_cli.md)
+* [A Minder account](./login.md)
+* [An enrolled GitHub token](./login.md#enrolling-the-github-provider) that is either an Owner in the organization or an Admin on the repositories
+* [A registered repository in Minder](./secret_scanning.md#register-repositories)
+* [The `secret_scanning`` rule type](./secret_scanning.md#creating-and-applying-profiles)
+* [A policy to open security advisories when secret scanning is off](./secret_scanning.md#creating-and-applying-profiles)
 
 ## Creating a profile with `remediate: on`
 
-Minder doesn't currently support editing profiles. In order to create the
-same profile with `remediate: on`, you need to delete the existing profile and create
-a new one.
+Minder doesn't currently support editing profiles, so we will create a new profile with `remediate: on`.
 
-Get the currently installed profiles:
-```shell
-minder profile list --provider=github
-```
-
-Find the ID of the profile you want to remove and delete it:
-```shell
-minder profile delete -i $ID
-```
-
-Edit the YAML file of the profile you want to use and set the `remediate` attribute
-to `on`:
+Edit the YAML file of the [profile from the secret-scanning tutorial](./secret_scanning.md#creating-and-applying-profiles)
+and set the `remediate` attribute to `on`:
 ```yaml
 ---
 version: v1

docs/docs/getting_started/secret_scanning.md

@@ -0,0 +1,118 @@
+---
+title: Enabling Secret Scanning
+sidebar_position: 40
+---
+
+# Enabling Secret Scanning using Minder Profiles
+
+Minder uses [profiles](../how-to/create_profile.md) to specify common,
+consistent configuration which should be enforced on all registered
+repositories.  In this tutorial, you will register a GitHub repository and
+create a profile that indicates whether secret scanning is enabled on the
+registered repositories.
+
+## Prerequisites
+
+* [The `minder` CLI application](./install_cli.md)
+* [A Minder account](./login.md)
+* [An enrolled GitHub token](./login.md#enrolling-the-github-provider) that is either an Owner in the organization or an Admin on the repositories
+
+## Register repositories
+
+Once you have enrolled a provider, you can register repositories from that provider.
+
+```bash
+minder repo register --provider github
+```
+
+This command will show a list of the public repositories available for
+registration.  Navigate through the repositories using the arrow keys and
+select one or more repositories for registration using the space key.  Press
+enter once you have selected all the desired repositories.
+
+You can also register a repository (or set of repositories) by name:
+
+```bash
+minder repo register --provider github --repo "owner:repo1,owner:repo2"
+```
+
+You can see the list of repositories registered in Minder with the `repo list` command:
+```bash
+minder repo list --provider github
+```
+
+## Creating and applying profiles
+
+A profile is a set of rules that you apply to your registered repositories.
+Before creating a profile, you need to ensure that all desired rule_types have been created in Minder.
+
+Start by creating a rule that checks if secret scanning is enabled and creates
+a security advisory alert if secret scanning is not enabled.  
+This is a reference rule provided by the Minder team in the [minder-rules-and-profiles repository](https://github.com/stacklok/minder-rules-and-profiles).
+
+For this exercise, we're going to download just the `secret_scanning.yaml`
+rule, and then use `minder rule_type create` to define the secret scanning rule.
+
+```bash
+curl -LO https://raw.githubusercontent.com/stacklok/minder-rules-and-profiles/main/rule-types/github/secret_scanning.yaml
+
+minder rule_type create -f secret_scanning.yaml
+```
+
+Next, create a profile that applies the secret scanning rule.
+
+Create a new file called `profile.yaml`.
+Paste the following profile definition into the newly created file.
+
+```yaml
+---
+version: v1
+type: profile
+name: github-profile
+context:
+  provider: github
+alert: "on"
+remediate: "off"
+repository:
+  - type: secret_scanning
+    def:
+      enabled: true
+```
+
+Create the profile in Minder:
+```
+minder profile create -f profile.yaml
+```
+
+Check the status of the profile:
+```
+minder profile_status list --profile github-profile
+```
+If all registered repositories have secret scanning enabled, you will see the `OVERALL STATUS` is `Success`, otherwise the 
+overall status is `Failure`.
+
+See a detailed view of which repositories satisfy the secret scanning rule:
+```
+minder profile_status list --profile github-profile --detailed
+```
+
+## Viewing alerts
+
+Disable secret scanning in one of the registered repositories, by following 
+[these instructions provided by GitHub](https://docs.github.com/en/code-security/secret-scanning/configuring-secret-scanning-for-your-repositories).
+
+Navigate to the repository on GitHub, click on the Security tab and view the Security Advisories.  
+Notice that there is a new advisory titled `minder: profile github-profile failed with rule secret_scanning`.
+
+Enable secret scanning in the same registered repository, by following
+[these instructions provided by GitHub](https://docs.github.com/en/code-security/secret-scanning/configuring-secret-scanning-for-your-repositories).
+
+Navigate to the repository on GitHub, click on the Security tab and view the Security Advisories.
+Notice that the advisory titled `minder: profile github-profile failed with rule secret_scanning` is now closed.
+
+## Delete registered repositories
+If you wish to delete a registered repository, you can do so with the following command:
+```bash
+minder repo delete -n $REPO_NAME --provider github
+```
+where `$REPO_NAME` is the fully-qualified name (`owner/name`) of the repository you wish to delete, for example `testorg/testrepo`.