Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

docs(#3344): add "Why Conforma?" documentation page #3349

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
fullsend-ai-coder wants to merge 1 commit into main
base: main
Choose a base branch
Loading
from agent/3344-why-conforma-docs
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/modules/ROOT/pages/index.adoc
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,9 @@ facts about an artifact such as:
* Validating container image provenance
* Evaluating {pol}[policies] over the container image provenance

To learn about the benefits of using Conforma over cosign directly, see
xref:why-conforma.adoc[Why Conforma?].

This documentation includes xref:ec.adoc[Conforma Command Line reference
documentation], and documentation on the
xref:verify-enterprise-contract.adoc[Verify Enterprise Contract Task]
Expand Down
95 changes: 95 additions & 0 deletions docs/modules/ROOT/pages/why-conforma.adoc
View file Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
= Why Conforma?

@fullsend-ai-review fullsend-ai-review Bot Jun 19, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[low] naming-conventions

The new document filename uses kebab-case (why-conforma.adoc). Among manually authored multi-word filenames in the pages directory, kebab-case (6 files) outnumbers underscore-case (2 files) by 3:1. The ec_* underscore files are auto-generated from CLI subcommand names. This file follows the dominant convention for hand-authored documentation pages — no change needed.


Conforma builds on top of https://docs.sigstore.dev/cosign/overview/[cosign]
to provide a comprehensive software supply chain verification platform. While
cosign handles cryptographic signature and attestation verification, Conforma
adds policy evaluation, batch validation, structured reporting, and CI/CD
integration that organizations need to enforce compliance at scale.

== Policy-as-code evaluation

With cosign alone, you can verify that an image was signed and that
attestations exist. Conforma goes further: it layers
https://www.openpolicyagent.org/[OPA/Rego] policy evaluation over those
verification results. This allows you to express organizational compliance
rules — such as requiring SLSA provenance, specific build tasks, or release
readiness criteria — as code that is evaluated automatically during
validation.

For example, `ec validate image` first verifies signatures and attestations
(akin to `cosign verify` and `cosign verify-attestation`), then evaluates
Rego policies defined in an
xref:configuration.adoc[EnterpriseContractPolicy] against the attestation
data.

== Batch and snapshot validation

cosign validates one image at a time. Conforma can validate multiple images
from an ApplicationSnapshot in a single invocation using the `--images` flag:

[source,shell]
----
ec validate image --images my-app.yaml
----

This is particularly useful in CI/CD pipelines where an application is
composed of multiple container images that must all pass policy checks before
a release proceeds.

== Structured output and reporting

cosign provides basic pass/fail output. Conforma supports multiple output
formats for different consumers:

* **JSON** and **YAML** — machine-readable results for downstream tooling
* **Text** — human-readable console output
* **JUnit** — test result format for CI/CD dashboard integration
* **Summary** and **Summary Markdown** — concise overviews for pull request
comments and reports
* **VSA** (Verification Summary Attestation) — a signed attestation recording
the verification result, which can be stored and checked later to avoid
redundant re-validation
* **Policy Input** — the raw data sent to the policy engine, useful for
debugging and policy development

Multiple formats can be produced simultaneously:

[source,shell]
----
ec validate image --image registry/name:tag --output json=results.json --output summary
----

== EnterpriseContractPolicy CRD integration

Conforma integrates with Kubernetes through the EnterpriseContractPolicy
custom resource definition (CRD). This allows teams to define policy
configurations declaratively — specifying policy sources, data sources,
public keys, and rule inclusion/exclusion criteria — and store them
alongside other Kubernetes resources.

See xref:configuration.adoc[Configuration] for details on policy
configuration options.

== Tekton task integration

Conforma ships ready-made Tekton tasks that can be embedded directly into
CI/CD pipelines. The
xref:verify-enterprise-contract.adoc[verify-enterprise-contract] task
runs Conforma validation as a pipeline step, making it straightforward to
gate releases on policy compliance without writing custom scripts.

== Built-in rule library

The https://github.com/conforma/policy[Conforma policy repository] provides
a curated library of Rego policy rules covering common supply chain
requirements:

* **SLSA provenance** — verify that build provenance meets SLSA level
requirements
* **Build task verification** — check that required build tasks were
executed
* **Release readiness** — enforce criteria that must be met before an
artifact is approved for release

These rules can be used as-is, extended, or combined with custom rules to
match your organization's specific requirements.
1 change: 1 addition & 0 deletions docs/modules/ROOT/partials/main_nav.adoc
View file Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
* xref:index.adoc[Home]
* xref:why-conforma.adoc[Why Conforma?]
* xref:configuration.adoc[Configuration]
* xref:policy_input.adoc[Policy Input]
* xref:types-of-attestations-and-manifests.adoc[Types of Attestations and Manifests]
Expand Down
Loading

AltStyle によって変換されたページ (->オリジナル) /