📖 Verifying the Authenticity and Integrity of Scorecard Results

README.md

@@ -40,6 +40,8 @@ ________
 - [Publishing Results](#publishing-results)
 - [Uploading Artifacts](#uploading-artifacts)
 - [Workflow Example](#workflow-example)
+[Verifying the Authenticity and Integrity of Scorecard Results](#verifying-the-authenticity-and-integrity-of-scorecard-results)
+
 ________
 
 The following GitHub triggers are supported: `push`, `schedule` (default branch only).
@@ -254,3 +256,32 @@ jobs:
         with:
           sarif_file: results.sarif
 ```
+## Verifying the Authenticity and Integrity of Scorecard Results
+The scorecard system uses several components from [sigstore](https://github.com/sigstore) to ensure tamper-resistant results. These components include cosign, fulcio, and rekor.
+
+Cosign signs the Scorecard action results with a cryptographic signature and stores the hash in a tamper-proof store called rekor, which uses technology based on Merkel trees (a specific type of data structure used in blockchain systems).
+
+Fulcio is a free certificate authority that issues short-lived code signing certificates for OpenID Connect identities, such as email addresses. Cosign uses fulcio for ephemeral keys and certificates.
+
+Rekor is a system that aims to provide an unchanging ledger of metadata generated within a software project's supply chain. It allows software maintainers and build systems to record signed metadata, which is then recorded in an immutable record using Merkel trees. Other parties can use this metadata to determine if they can trust the lifecycle of an object. Cosign stores the signed hash of the result in rekor to further enhance the tamper resistance of the Scorecard system.
+
+You can learn more about Merkel trees at this link: https://en.wikipedia.org/wiki/Merkle_tree
+
+
+This diagram illustrates how Scorecard validates the authenticity and integrity of the results it produces. This process allows the repository owner to verify the authenticity and integrity of Scorecard results and make them available for others to access and use.
+
+```mermaid
+sequenceDiagram
+Scorecard action ->> Scorecard action: Run scorecard for repository
+Scorecard action ->> Scorecard action: Generate result.json
+Note over cosign, Scorecard action: Scorecard  embeds the cosign library
+cosign ->> rekor.sigstore.dev: Sign and store hash of result.json 
+Scorecard action->>api.securityscorecards.dev: Post result.json
+Note over api.securityscorecards.dev: Validates the result
+api.securityscorecards.dev->>Scorecard action: Return status  
+```
+1. The Scorecard Action runs a Scorecard analysis on a repository.
+1. The action generates a file called result.json that contains the analysis results.
+1. The cosign library, which is embedded in the Scorecard action, signs and stores a hash of result.json file in the `rekor.sigstore.dev` service.
+1. The result.json file is posted to the `api.securityscorecards.dev` service.
+1. The `api.securityscorecards.dev` service validates the authenticity of the results with `rekor.sigstore.dev` before storing the results.