From 17da2db80e647be9f3072557f05aeadacc398ead Mon Sep 17 00:00:00 2001
From: Greg Mohler <callmegreg@github.com>
Date: Fri, 22 Nov 2024 14:37:51 -0500
Subject: [PATCH] more readme updates

---
 README.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 52 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 397e433..b336e40 100644
--- a/README.md
+++ b/README.md
@@ -51,7 +51,12 @@ By default, when any secrets are found the Action will also add a comment to the
 
 ### Step Output of Alert Metadata (python runtime only)
 
-When running the Action with the `python` runtime option, the Action will also provide a summary of the secrets introduced in the pull request as a step output variable, `alerts`. You can access this step output in subsequent steps in your workflow. For example, to print the alert metadata in the workflow log:
+When running the Action with the `python` runtime option, the Action will also provide a summary of the secrets introduced in the pull request as a step output variable, `alerts`. You can access this step output in subsequent steps in your workflow for any further processing that you would like to perform.
+
+> [!NOTE]
+> The `alerts` step output does NOT include secret values.
+
+An example of how to access this step output in your Actions workflow is shown below:
 
 ```yaml
 [...]
@@ -62,10 +67,10 @@ When running the Action with the `python` runtime option, the Action will also p
     token: ${{ steps.app-token.outputs.token }}
     runtime: 'python'
 
-- name: 'Process step output'
+- name: 'Log alert metadata'
   if: always()
   run: |
-    echo "${{ steps.secret-alert-check.outputs.alerts }}"
+    echo ${{ steps.secret-alert-check.outputs.alerts }}
 ```
 
 The `alerts` variable is set to a JSON array with the following fields for each alert detected in the PR:
@@ -77,6 +82,50 @@ The `alerts` variable is set to a JSON array with the following fields for each
 - `resolution`: The resolution of the alert
 - `html_url`: The URL to the alert in the GitHub UI
 
+An example of the `alerts` step output variable is shown below, where two different secrets were introduced in a PR:
+```json
+[
+    {
+        "number": 68,
+        "secret_type": "hardcoded_password",
+        "push_protection_bypassed": false,
+        "push_protection_bypassed_by": null,
+        "state": "open",
+        "resolution": null,
+        "html_url": "https://github.com/callmegreg-demo-org/ss-demo-repo/security/secret-scanning/68"
+    },
+    {
+        "number": 67,
+        "secret_type": "hardcoded_password",
+        "push_protection_bypassed": true,
+        "push_protection_bypassed_by": {
+            "login": "CallMeGreg",
+            "id": 110078080,
+            "node_id": "U_kgDOBo-ogA",
+            "avatar_url": "https://avatars.githubusercontent.com/u/110078080?v=4",
+            "gravatar_id": "",
+            "url": "https://api.github.com/users/CallMeGreg",
+            "html_url": "https://github.com/CallMeGreg",
+            "followers_url": "https://api.github.com/users/CallMeGreg/followers",
+            "following_url": "https://api.github.com/users/CallMeGreg/following{/other_user}",
+            "gists_url": "https://api.github.com/users/CallMeGreg/gists{/gist_id}",
+            "starred_url": "https://api.github.com/users/CallMeGreg/starred{/owner}{/repo}",
+            "subscriptions_url": "https://api.github.com/users/CallMeGreg/subscriptions",
+            "organizations_url": "https://api.github.com/users/CallMeGreg/orgs",
+            "repos_url": "https://api.github.com/users/CallMeGreg/repos",
+            "events_url": "https://api.github.com/users/CallMeGreg/events{/privacy}",
+            "received_events_url": "https://api.github.com/users/CallMeGreg/received_events",
+            "type": "User",
+            "user_view_type": "public",
+            "site_admin": true
+        },
+        "state": "resolved",
+        "resolution": "false_positive",
+        "html_url": "https://github.com/callmegreg-demo-org/ss-demo-repo/security/secret-scanning/67"
+    }
+]
+```
+
 ## Security Model Considerations
 * To be clear, this Action will surface secret scanning alerts to anyone with `Read` access to a repository. This level of visibility is consistent with the access needed to see any raw secrets already commited to the repository's commit history.