rename import, implement attestation, cleanup name (#20)

* rename import, implement attestation, cleanup name

* update e2e test

INSTALLATION.md

@@ -0,0 +1,94 @@
+# aactl
+
+You can install `aactl` CLI using one of the following ways:
+
+* [Go](#go)
+* [Homebrew](#homebrew)
+* [RHEL/CentOS](#rhelcentos)
+* [Debian/Ubuntu](#debianubuntu)
+* [Binary](#binary)
+
+See the [release section](https://github.com/GoogleCloudPlatform/aactl/releases/latest) for `aactl` checksums and SBOMs.
+
+### Go
+
+If you have Go 1.17 or newer, you can install latest `aactl` using:
+
+```shell
+go install github.com/GoogleCloudPlatform/aactl/cmd/aactl@latest
+```
+
+### Homebrew
+
+On Mac or Linux, you can install `aactl` with [Homebrew](https://brew.sh/):
+
+```shell
+brew tap GoogleCloudPlatform/aactl https://github.com/GoogleCloudPlatform/aactl
+brew install aactl
+```
+
+New release will be automatically picked up when you run `brew upgrade`
+
+
+### RHEL/CentOS
+
+```shell
+rpm -ivh https://github.com/GoogleCloudPlatform/aactl/releases/download/v$VERSION/aactl-$VERSION_Linux-amd64.rpm
+```
+
+### Debian/Ubuntu
+
+```shell
+wget https://github.com/aquasecurity/aactl/releases/download/v$VERSION/aactl-$VERSION_Linux-amd64.deb
+sudo dpkg -i aactl-$VERSION_Linux-64bit.deb
+```
+
+### Binary 
+
+You can also download the [latest release](https://github.com/GoogleCloudPlatform/aactl/releases/latest) version of `aactl` for your operating system/architecture from [here](https://github.com/GoogleCloudPlatform/aactl/releases/latest). Put the binary somewhere in your $PATH, and make sure it has that executable bit.
+
+> The official `aactl` releases include SBOMs
+
+## Prerequisites 
+
+Since you are interested in `aactl`, you probably already have GCP account and project. If not, you learn about creating and managing projects [here](https://cloud.google.com/resource-manager/docs/creating-managing-projects). The other prerequisites include:
+
+### APIs
+
+`aactl` also depends on a few GCP service APIs. To enable these, run:
+
+```shell
+gcloud services enable containeranalysis.googleapis.com
+```
+
+### Roles
+
+Make sure you have the following Identity and Access Management (IAM) roles in each project: 
+
+> Learn how to grant multiple IAM roles to a user [here](https://cloud.google.com/iam/docs/granting-changing-revoking-access#multiple-roles)
+
+```shell
+roles/containeranalysis.occurrences.editor
+roles/containeranalysis.notes.editor
+```
+
+If you experience any issues, you can see the project level policy using following command:
+
+```shell
+gcloud projects get-iam-policy $PROJECT_ID --format=json > policy.json
+```
+
+### Credentials
+
+When running locally, `aactl` will look for Google account credentials in one of the well-known locations. To ensure your Application Default Credentials (ADC) are used by the `aactl` run this `gcloud` command and follow the prompts:
+
+```shell
+gcloud auth application-default login
+```
+
+> More about ADC [here](https://cloud.google.com/docs/authentication/provide-credentials-adc)
+
+
+## Licensing
+
+Code in this repository is licensed under the Apache 2.0. See [LICENSE](LICENSE).

README.md

@@ -1,17 +1,16 @@
-# Google Cloud Platform Artifact Analysis Import Utility
+# aactl
 
-Google [Container Analysis service](https://cloud.google.com/container-analysis/docs/container-analysis) data import utility, supports OSS vulnerability scanner reports, SLSA provenance, and sigstore attestations.
+Google [Container Analysis (AA)](https://cloud.google.com/container-analysis/docs/container-analysis) service data import utility, supports OSS vulnerability scanner reports, SLSA provenance, and sigstore attestations.
 
-```shell
-aactl import --project $project \
-             --source $image \
-             --file report.json \
-             --format snyk
-```
+> Installation instruction with support for Go, Homebrew, RHEL/CentOS, Debian/Ubuntu, and Binary are available [here](INSTALLATION.md).
 
-> The $image variable in the above example is the fully qualified URI of the image including its digest (e.g. `us-docker.pkg.dev/project/repo/image@sha256:397d453...`).
+## Usage 
+
+`aactl` supports imports of two data types: `vulnerability` and `attestation`.
 
-The currently supported scanners/formats include:
+### Vulnerability 
+
+To import vulnerabilities output by either [grype](https://github.com/anchore/grype), [snyk](https://github.com/snyk/cli), [trivy](https://github.com/aquasecurity/trivy) scanners, start by exporting the report in JSON format: 
 
 * [grype](https://github.com/anchore/grype)
 
@@ -25,104 +24,38 @@ The currently supported scanners/formats include:
 
   `trivy image --format json --output report.json $image`
 
-To review the imported vulnerabilities:
+Once you have the vulnerability file, importing that file into AA using `aactl`:
 
 ```shell
-gcloud artifacts docker images list $repo \
-  --show-occurrences \
-  --format=json \
-  --occurrence-filter='kind="VULNERABILITY" AND noteProjectId="$project" AND resource_url="$image" AND noteId="CVE-2005-2541"'
+aactl vulnerability --project $project \
+                    --source $image \
+                    --file report.json \
+                    --format snyk
 ```
 
-## Installation 
-
-You can install `aactl` CLI using one of the following ways:
-
-* [Go](#go)
-* [Homebrew](#homebrew)
-* [RHEL/CentOS](#rhelcentos)
-* [Debian/Ubuntu](#debianubuntu)
-* [Binary](#binary)
-
-See the [release section](https://github.com/GoogleCloudPlatform/aactl/releases/latest) for `aactl` checksums and SBOMs.
-
-## Go
-
-If you have Go 1.17 or newer, you can install latest `aactl` using:
-
-```shell
-go install github.com/GoogleCloudPlatform/aactl/cmd/aactl@latest
-```
-
-## Homebrew
-
-On Mac or Linux, you can install `aactl` with [Homebrew](https://brew.sh/):
-
-```shell
-brew tap GoogleCloudPlatform/aactl https://github.com/GoogleCloudPlatform/aactl
-brew install aactl
-```
-
-New release will be automatically picked up when you run `brew upgrade`
-
-
-## RHEL/CentOS
-
-```shell
-rpm -ivh https://github.com/GoogleCloudPlatform/aactl/releases/download/v$VERSION/aactl-$VERSION_Linux-amd64.rpm
-```
-
-## Debian/Ubuntu
-
-```shell
-wget https://github.com/aquasecurity/aactl/releases/download/v$VERSION/aactl-$VERSION_Linux-amd64.deb
-sudo dpkg -i aactl-$VERSION_Linux-64bit.deb
-```
-
-## Binary 
-
-You can also download the [latest release](https://github.com/GoogleCloudPlatform/aactl/releases/latest) version of `aactl` for your operating system/architecture from [here](https://github.com/GoogleCloudPlatform/aactl/releases/latest). Put the binary somewhere in your $PATH, and make sure it has that executable bit.
-
-> The official `aactl` releases include SBOMs
-
-## Prerequisites 
-
-Since you are interested in `aactl`, you probably already have GCP account and project. If not, you learn about creating and managing projects [here](https://cloud.google.com/resource-manager/docs/creating-managing-projects). The other prerequisites include:
-
-### APIs
-
-`aactl` also depends on a few GCP service APIs. To enable these, run:
-
-```shell
-gcloud services enable containeranalysis.googleapis.com
-```
-
-### Roles
-
-Make sure you have the following Identity and Access Management (IAM) roles in each project: 
+> The $image variable in the above example is the fully qualified URI of the image including its digest (e.g. `us-docker.pkg.dev/project/repo/image@sha256:397d453...`).
 
-> Learn how to grant multiple IAM roles to a user [here](https://cloud.google.com/iam/docs/granting-changing-revoking-access#multiple-roles)
+To review the imported vulnerabilities in GCP:
 
 ```shell
-roles/containeranalysis.occurrences.editor
-roles/containeranalysis.notes.editor
+gcloud artifacts docker images list $repo \
+  --show-occurrences \
+  --format json \
+  --occurrence-filter 'kind="VULNERABILITY" AND noteProjectId="$project" AND resource_url="$image" AND noteId="CVE-2005-2541"'
 ```
 
-If you experience any issues, you can see the project level policy using following command:
-
-```shell
-gcloud projects get-iam-policy $PROJECT_ID --format=json > policy.json
-```
+> You can also navigate to Artifact Registry to view the vulnerabilities there. 
 
-### Credentials
+### Attestation
 
-When running locally, `aactl` will look for Google account credentials in one of the well-known locations. To ensure your Application Default Credentials (ADC) are used by the `aactl` run this `gcloud` command and follow the prompts:
+In addition to vulnerabilities, `aactl` can also import [sigstore](https://github.com/sigstore) attestations:
 
 ```shell
-gcloud auth application-default login
+aactl attestation --project $project \
+                  --source $image \
 ```
 
-> More about ADC [here](https://cloud.google.com/docs/authentication/provide-credentials-adc)
+> The $image variable in the above example is the fully qualified URI of the image including its digest (e.g. `us-docker.pkg.dev/project/repo/image@sha256:397d453...`).
 
 ## Contributing
 

cmd/aactl/cli/import-sigstore.go → cmd/aactl/cli/attest.go

@@ -15,42 +15,35 @@
 package cli
 
 import (
-	"github.com/GoogleCloudPlatform/aactl/pkg/sigstore"
+	"github.com/GoogleCloudPlatform/aactl/pkg/attestation"
 	"github.com/GoogleCloudPlatform/aactl/pkg/types"
 	"github.com/pkg/errors"
 	c "github.com/urfave/cli/v2"
 )
 
 var (
-	impSigstoreCmd = &c.Command{
-		Name:    "import-sigstore",
-		Aliases: []string{"impst"},
-		Usage:   "import Sigstore-format metadata",
-		Action:  importSigstoreCmd,
+	attestCmd = &c.Command{
+		Name:    "attestation",
+		Aliases: []string{"att", "attest"},
+		Usage:   "import attestation metadata",
+		Action:  attestationCmd,
 		Flags: []c.Flag{
 			projectFlag,
 			sourceFlag,
-			formatFlag,
 		},
 	}
 )
 
-func importSigstoreCmd(c *c.Context) error {
-	f, err := types.ParseSigstoreFormat(c.String(formatFlag.Name))
-	if err != nil {
-		return errors.Wrap(err, "error parsing source format")
-	}
-
-	opt := &types.ImportSigstoreOptions{
+func attestationCmd(c *c.Context) error {
+	opt := &types.AttestationOptions{
 		Project: c.String(projectFlag.Name),
 		Source:  c.String(sourceFlag.Name),
-		Format:  f,
 		Quiet:   isQuiet(c),
 	}
 
 	printVersion(c)
 
-	if err := sigstore.Import(c.Context, opt); err != nil {
+	if err := attestation.Import(c.Context, opt); err != nil {
 		return errors.Wrap(err, "error executing command")
 	}
 

cmd/aactl/cli/cmd.go

@@ -92,7 +92,7 @@ func newApp(version, commit, date string) (*c.App, error) {
 		},
 		Commands: []*c.Command{
 			impCmd,
-			impSigstoreCmd,
+			attestCmd,
 		},
 	}
 

cmd/aactl/cli/import.go → cmd/aactl/cli/vuln.go

@@ -23,8 +23,8 @@ import (
 
 var (
 	impCmd = &c.Command{
-		Name:    "import",
-		Aliases: []string{"imp"},
+		Name:    "vulnerability",
+		Aliases: []string{"vul", "vuln", "vulns"},
 		Usage:   "import vulnerabilities from file",
 		Action:  importCmd,
 		Flags: []c.Flag{
@@ -42,7 +42,7 @@ func importCmd(c *c.Context) error {
 		return errors.Wrap(err, "error parsing source format")
 	}
 
-	opt := &types.ImportOptions{
+	opt := &types.VulnerabilityOptions{
 		Project: c.String(projectFlag.Name),
 		Source:  c.String(sourceFlag.Name),
 		File:    c.String(fileFlag.Name),

pkg/sigstore/convert.go → pkg/attestation/convert.go

@@ -12,10 +12,9 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package sigstore
+package attestation
 
 import (
-	"context"
 	"encoding/json"
 	"fmt"
 	"strings"
@@ -29,7 +28,8 @@ import (
 	"google.golang.org/protobuf/types/known/structpb"
 )
 
-func Convert(ctx context.Context, nr utils.NoteResource, resourceURL string, env *provenance.Envelope) (*g.Note, *g.Occurrence, error) {
+// Convert converts a provenance statement to a Grafeas note and occurrence.
+func Convert(nr utils.NoteResource, resourceURL string, env *provenance.Envelope) (*g.Note, *g.Occurrence, error) {
 	prov, err := getProvenance(env)
 	if err != nil {
 		return nil, nil, errors.Wrap(err, "error getting provenance")

pkg/sigstore/import.go → pkg/attestation/import.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package sigstore
+package attestation
 
 import (
 	"context"
@@ -32,7 +32,8 @@ import (
 	"google.golang.org/grpc/status"
 )
 
-func Import(ctx context.Context, opt *types.ImportSigstoreOptions) error {
+// Import imports attestation metadata from a source.
+func Import(ctx context.Context, opt *types.AttestationOptions) error {
 	if opt == nil {
 		return errors.New("options required")
 	}
@@ -74,7 +75,7 @@ func importEnvelopes(ctx context.Context, envs []*provenance.Envelope, nr utils.
 	defer c.Close()
 
 	for _, env := range envs {
-		n, o, err := Convert(ctx, nr, resourceURL, env)
+		n, o, err := Convert(nr, resourceURL, env)
 		if err != nil {
 			return errors.Wrap(err, "error importing envelopes")
 		}

pkg/sigstore/import_test.go → pkg/attestation/import_test.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package sigstore
+package attestation
 
 import (
 	"testing"
@@ -25,9 +25,9 @@ import (
 func TestInvalidImport(t *testing.T) {
 	err := Import(context.TODO(), nil)
 	assert.Error(t, err)
-	err = Import(context.TODO(), &types.ImportSigstoreOptions{})
+	err = Import(context.TODO(), &types.AttestationOptions{})
 	assert.Error(t, err)
-	err = Import(context.TODO(), &types.ImportSigstoreOptions{
+	err = Import(context.TODO(), &types.AttestationOptions{
 		Source: "us-docker.pkg.dev/project/repo/img@sha256:f6efe...",
 	})
 	assert.Error(t, err)