Skip to content

Commit

Permalink
Fix witness run readme (#7)
Browse files Browse the repository at this point in the history 
* fix: example in the README (landing page)

The given example in the README.md has invalid parameters according with
action.yml

Signed-off-by: Kairo Araujo <kairo.araujo@testifysec.com>

* fix: little misspelling

Signed-off-by: Kairo Araujo <kairo.araujo@testifysec.com>

* doc: short the length for README.md text and param

- Reduce the length of README.md source code to less than 100 col to
  easy maintain

- Higlight the parameters in the text

Signed-off-by: Kairo Araujo <kairo.araujo@testifysec.com>

* doc: Add a better example building the software

Signed-off-by: Kairo Araujo <kairo.araujo@testifysec.com>

* fix: Update version in the example

If the user copy/paste the example will cause an error in their GHA.

```
Run testifysec/witness-run-action@v0.1
Running command: witness run --archivista-server https://archivista.testifysec.io -a environment -a git -a github -s build --trace false --outfile /tmp/build-attestation.json -- /bin/sh -c make build
/home/runner/work/_actions/testifysec/witness-run-action/v0.1/node_modules/@actions/io/lib/io.js:171
                    throw new Error(`Unable to locate executable file: ${tool}. Please verify either the file path exists or the file can be found within a directory specified by the PATH environment variable. Also check the file mode to verify the file is executable.`);

```

Signed-off-by: Kairo Araujo <kairo.araujo@testifysec.com>

---------

Signed-off-by: Kairo Araujo <kairo.araujo@testifysec.com>
  • Loading branch information
@kairoaraujo
kairoaraujo committed Feb 12, 2024
1 parent 40aa4ef commit 2bb760e
Showing 1 changed file with 38 additions and 14 deletions.
52 changes: 38 additions & 14 deletions README.md
View file
Expand Up @@ -2,7 +2,9 @@

# Witness Run GitHub Action

This GitHub Action allows you to create an attestation for your CI process using the Witness tool. It supports optional integration with Sigstore for signing and Archivista for attestation storage and distibution.
This GitHub Action allows you to create an attestation for your CI process using
the Witness tool. It supports optional integration with Sigstore for signing and
Archivista for attestation storage and distibution.

## Usage

Expand All @@ -23,36 +25,58 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
uses: actions/checkout@v0.1.3

- name: Witness Run
uses: testifysec/witness-run-action@v0.1
uses: testifysec/witness-run-action@v1
with:
step: test
use-archivista: true
use-sigstore: true
command: touch hello.txt
step: build
enable-archivista: false
enable-sigstore: false
command: make build
```

## Using Sigstore and Archivista Flags
This action supports the use of Sigstore and Archivista for creating attestations. By enabling these options, you create a public record of your attestations, which can be useful for transparency and compliance.
This action supports the use of Sigstore and Archivista for creating attestations.
By enabling the option `enable-archivista`, you create a public record of your
attestations, which can be useful for transparency and compliance.

### Sigstore
Sigstore is an open-source platform for securely signing software artifacts. When the use-sigstore flag is set to true, this action will use Sigstore for signing the attestation. This creates a publicly verifiable record of the attestation on the Sigstore public instance, sigstore.dev
Sigstore is an open-source platform for securely signing software artifacts. When
the `enable-sigstore` flag is set to true, this action will use Sigstore for signing
the attestation. This creates a publicly verifiable record of the attestation on
the Sigstore public instance, sigstore.dev

### Archivista
Archivista is a server that stores and retrieves attestations. When the enable-archivista flag is set to true, this action will use Archivista for storing and retrieving attestations. By default, the attestations are stored on a public Archivista server, archivista.testifysec.io, making the details publicly accessible. This server also has no guarantees on data availability or itegrity.
Archivista is a server that stores and retrieves attestations. When the `enable-archivista`
flag is set to true, this action will use Archivista for storing and retrieving
attestations. By default, the attestations are stored on a public Archivista server,
`https://archivista.testifysec.io`, making the details publicly accessible. This server
also has no guarantees on data availability or integrity.

### TimeStamping

By default when using Sigstore, this action utilizes FreeTSA, a free and public Timestamp Authority (TSA) service, to provide trusted timestamping for your attestations. Timestamping is a critical aspect of creating non-repudiable and legally binding attestations. FreeTSA offers a reliable and convenient solution for timestamping without the need for setting up and managing your own TSA. When using this action, the timestamp-servers input is set to FreeTSA's service (https://freetsa.org/) by default, ensuring your attestations are properly timestamped with a trusted and publicly verifiable source.
By default when using Sigstore, this action utilizes FreeTSA, a free and public
Timestamp Authority (TSA) service, to provide trusted timestamping for your
attestations. Timestamping is a critical aspect of creating non-repudiable and
legally binding attestations. FreeTSA offers a reliable and convenient solution for
timestamping without the need for setting up and managing your own TSA. When using
this action, the `timestamp-servers` input is set to FreeTSA's service (https://freetsa.org/)
by default, ensuring your attestations are properly timestamped with a trusted and
publicly verifiable source.

### Privacy Considerations
If you want to keep the details of your attestations private, you can set up and host your own instances of Archivista and Sigstore. This allows you to manage access control and ensure that only authorized users can view the attestation details.
If you want to keep the details of your attestations private, you can set up
and host your own instances of Archivista and Sigstore. This allows you to manage
access control and ensure that only authorized users can view the attestation details.

To use your own instances, set the archivista-server input to the URL of your Archivista server, and the fulcio input to the address of your Sigstore instance. Additionally, you'll need to configure the fulcio-oidc-client-id and fulcio-oidc-issuer inputs to match your Sigstore instance's OIDC configuration.
To use your own instances, set the `archivista-server` input to the URL of your
Archivista server, and the fulcio input to the address of your Sigstore instance.
Additionally, you'll need to configure the `fulcio-oidc-client-id` and `fulcio-oidc-issuer`
inputs to match your Sigstore instance's OIDC configuration.

Please consult the documentation for Archivista and Sigstore on how to set up and host your own instances.
Please consult the documentation for Archivista and Sigstore on how to set up and
host your own instances.


### Inputs
Expand Down

0 comments on commit 2bb760e

Please sign in to comment.