in-toto · colek42 · Nov 3, 2022 · Nov 3, 2022
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -0,0 +1,134 @@
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[community@testifysec.com](mailto:community@testifysec.com).
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations
+
diff --git a/README.md b/README.md
@@ -1,44 +1,88 @@
-# archivist
+<p align="center">
+  <img src="docs/assets/logo.png">
+</p>
 
-Archivist helps organizations discover attestations and provenance of their software artifacts.
+# Archivist
 
-Archivist is an attestation store with first-class support for Witness attestations but supports any [in-toto](https://in-toto.io) attestation making it work well with other open-source tools that generate in-toto attestations.
+Archivist is a graph and storage service for [in-toto](https://in-toto.io) attestations. Archivist enables the discovery
+and retrieval of attestations for software artifacts.
 
-## building
+## How Archivist Works
 
-```sh
-$ docker-compose up --build
+When an attestation is uploaded to Archivist it will store the entire attestation in a configured object store as well
+as scrape some data from the attestation and store it in a queryable metadata store. This metadata is exposed through a
+GraphQL API. This enables queries such as finding all attestations related to an artifact with a specified hash or
+finding all attestations that recorded the use of a specific dependency.
 
-$ archivistctl attestation.json
-```
+Archivist uses Subjects on the [in-toto
+Statement](https://github.com/in-toto/attestation/blob/main/spec/README.md#statement) as edges on this graph. Producers
+of attestations (such as [Witness](https://github.com/testifysec/witness) can use these subjects as a way to expose
+relationships between attestations.
 
-## shutting down
+For example when attesting that an artifact was compiled the compiled artifact may be a subject, as well as the git
+commit hash the artifact was built from. This would allow traversing the graph by the commit hash to find other relevant
+attestations such as those describing code reviews, testing, and scanning that happened on that git commit.
 
-```sh
-$ docker-compose down
-```
+## Running Archivist
+
+A public instance of Archivist is running [here](https://archivist.testifysec.io) for testing purposes. The data in this
+instance is open to the world and there are currently no SLAs defined for this instance.
 
-## Running archivist out of docker-compose
+Archivist requires a MySQL database as well as a compatible file store. Compatible file stores include a local directory
+or any S3 compatible store.
 
-This application is configured through the environment. The following environment variables can be used:
+A docker compose file is included in the repository that will run a local instance of Archivist along with the necessary
+services for it to operate. These include Minio and MySQL. Simply cloning the repo and running
 
-```sh
-KEY                        TYPE             DEFAULT                     REQUIRED    DESCRIPTION
-ARCHIVIST_ENABLE_SPIFFE    True or False    TRUE                                    Enable SPIFFE support
-ARCHIVIST_LISTEN_ON        URL              unix:///listen.on.socket                url to listen on
-ARCHIVIST_LOG_LEVEL        String           INFO                                    Log level
+```
+docker compose up --build -d
 ```
 
-Running in a test environment:
+is enough to get a local instance of Archivist up and running. Archivist will be listening at `http://localhost:8082` by
+default with this docker compose file.
 
-```sh
-$ go install ./cmd/archivist
-$ ARCHIVIST_ENABLE_SPIFFE=false ARCHIVIST_LISTEN_ON=tcp://127.0.0.1:8080 archivist
-```
+### Configuration
+
+Archivist is configured through environment variables currently.
+
+| Variable | Default Value | Description |
+| -------- | ------------- | ----------- |
+| ARCHIVIST_LISTEN_ON | tcp://127.0.0.1:8082 | URL endpoint for Archivist to listen on |
+| ARCHIVIST_LOG_LEVEL | INFO | Log level. Options are DEBUG, INFO, WARN, ERROR |
+| ARCHIVIST_CORS_ALLOW_ORIGINS | | Comma separated list of origins to allow CORS requests from |
+| ARCHIVIST_SQL_STORE_CONNECTION_STRING | root:example@tcp(db)/testify | SQL store connection string |
+| ARCHIVIST_STORAGE_BACKEND | | Backend to use for attestation storage. Options are FILE, BLOB, or empty string for disabled. |
+| ARCHIVIST_FILE_SERVE_ON | | What address to serve files on. Only valid when using FILE storage backend. |
+| ARCHIVIST_FILE_DIR | /tmp/archivist/ | Directory to store and serve files. Only valid when using FILE storage backend. |
+| ARCHIVIST_BLOB_STORE_ENDPOINT | 127.0.0.1:9000 | URL endpoint for blob storage. Only valid when using BLOB storage backend. |
+| ARCHIVIST_BLOB_STORE_ACCESS_KEY_ID | | Blob store access key id. Only valid when using BLOB storage backend. |
+| ARCHIVIST_BLOB_STORE_SECRET_ACCESS_KEY_ID | | Blob store secret access key id. Only valid when using BLOB storage backend. |
+| ARCHIVIST_BLOB_STORE_USE_TLS | TRUE | Use TLS for BLOB storage backend. Only valid when using BLOB storage backend. |
+| ARCHIVIST_BLOB_STORE_BUCKET_NAME | | Bucket to use for storage.  Only valid when using BLOB storage backend. |
+| ARCHIVIST_ENABLE_GRAPHQL | TRUE | Enable GraphQL Endpoint |
+| ARCHIVIST_GRAPHQL_WEB_CLIENT_ENABLE | TRUE | Enable GraphiQL, the GraphQL web client |
+
+
+## Using Archivist
 
-`archivectl` is used to upload and download DSSE objects from the command line. As of now, it only uploads then
-downloads the same object to test end to end functionality. This command will be built up in time.
+Archivist exposes two HTTP endpoints to upload or download attestations:
 
-```sh
-$ archivistctl file-to-upload-and-downlaod
 ```
+POST /upload - Uploads an attestation to Archivist. The attestation is to be in the request's body
+```
+
+```
+GET /download/:gitoid: - Downloads an attestation with provided gitoid from Archivist
+```
+
+Additionally Archivist exposes a GraphQL API. By default the GraphQL playground is enabled and available at root.
+
+`archivistctl` is a CLI tool in this repository that is available to interact with an Archivist instance. `archivistctl`
+is capable of uploading and downloading attestations as well as doing some basic queries such as finding all
+attestations with a specified subject and retrieving all subjects for a specified attestation.
+
+## What's Next
+
+We would like to expand the types of data Archivist can ingest as well as expand the metadata Archivist collected about
+ingested data. If you have ideas or use cases for Archivist, feel free to [contact us](mailto:info@testifysec.io) or
+create an issue!
diff --git a/docs/assets/logo.png b/docs/assets/logo.png