rode / rode

Rode facilitates Automated Governance in your software supply chain. This repository contains the rode API which is the primary interface between the rode UI or rode Collectors and metadata storage in Grafeas. The rode API provides functions for metadata search and storage as well as policy creation and evaluation.

rode

\rōd\ - a line (as of rope or chain) used to attach an anchor to a boat

rode provides the collection, attestation and enforcement of policies in your software supply chain.

Why rode?

Enterprises require a secure and reliable software delivery lifecycle to meet the needs of audit and compliance. This has traditionaly been implemented by applying governance and additional process. rode aims to meet this need by enabling Automated Governance. Automated Governance allows us to move the existing change approval process left by automating stages in software delivery that may currently exist as manual activities. This is possible by building a codified system of trust and authority for the entire software lifecycle. rode facilitates the collection and organization of important software supply chain metadata and provides a method of Automated Governance via Policy as Code.

rode Architecture

The overall architecture of rode is built around bringing together tools built with the needs of governance in mind. The system of rode consists of Collectors, the rode API, Grafeas, and Open Policy Agent. We have extended the Grafeas storage backend to use Elasticsearch. These tools work together to enable Automated Governance.

Collectors

Collectors package the metadata in the form of an "occurrence". These occurrences represent verifiable, individual software delivery process events. Collectors provide an entrypoint to the rode system by helping standardize the way metadata is brought in. They will be "purpose built" to collect metadata from any of the tools you are using in your software delivery toolchain.

Grafeas

Grafeas is an open source project that provides an API and storage layer for artifact metadata.

Information that is gathered by collectors is ultimately stored within Grafeas as Occurrences. Occurrences represent a particular piece of metadata about an artifact, and they can be used by Rode when evaluating policies against artifacts. Information such as an artifact's vulnerabilities, how it was built, and the quality of the codebase that produced the artifact can be fed to a policy in order to determine whether that artifact meets a certain set of standards set by your organization.

The primary way that Grafeas adds value to the rode project is through its models around how artifact metadata should be tracked and stored. Over time, we plan to add new types of Occurrences to Grafeas to represent artifact metadata concepts that we believe are important, but aren't currently represented in the existing models.

We currently use a custom backend for Grafeas that's based on Elasticsearch.

From Grafeas docs:

Grafeas is an open-source artifact metadata API that provides a uniform way to audit and govern your software supply chain. Grafeas defines an API spec for managing metadata about software resources, such as container images, Virtual Machine (VM) images, JAR files, and scripts. You can use Grafeas to define and aggregate information about your project's components. Grafeas provides organizations with a central source of truth for tracking and enforcing policies across an ever growing set of software development teams and pipelines. Build, auditing, and compliance tools can use the Grafeas API to store, query, and retrieve comprehensive metadata on software components of all kinds.

Open Policy Agent

Open Policy Agent, or OPA is the open source standard for implementing Policy as Code.

rode uses OPA as a means to apply and validate policy via Rego policies stored in source control (Poicy as Code). By using the occurrence and attestation metadata stored in Grafeas as inputs for policy, all resources can be validated as needed. rode provides a method to bring the policy and metadata together as a means for enabling Automated Governance.

The Open Policy Agent (OPA, pronounced “oh-pa”) is an open source, general-purpose policy engine that unifies policy enforcement across the stack. OPA provides a high-level declarative language that lets you specify policy as code and simple APIs to offload policy decision-making from your software. You can use OPA to enforce policies in microservices, Kubernetes, CI/CD pipelines, API gateways, and more.

Policy Evaluation

..

Installation

Helm

Add Helm repositories

helm repo add rode https://rode.github.io/charts
helm repo add elastic https://helm.elastic.co
helm repo update 

Install Rode

helm install rode rode/rode --set grafeas-elasticsearch.grafeas.elasticsearch.username=grafeas --set grafeas-elasticsearch.grafeas.elasticsearch.password=BAD_PASSWORD

See Rode Helm chart for more details.

Documentation

• Development
• API Reference

rode's Issues

Specify routing when creating/updating policy counter document

See this discussion: #95 (comment), #95 (comment)

Update fetch occurrences method

Update fetch occurrences method in Rode to fetch build occurrences which reference the primary resource URI and compile a list of related resource URIs then fetch and return occurrences for all resource URIs

Add a policy identifier field in the policy schema

The policy identifier field in the policy schema will describe whether a policy belongs to npm,docker,maven. It answers the question of "What does the policy target?"

Move internal protobufs into their own package

Originally posted by @alexashley in #100 (comment)

Create endpoints for CRUD operations on policies

Rode requires new endpoints to allow for CRUD operations on REGO policies. These policies would then be stored in elasticsearch.
Upon an edit or creation of a rego policy, there must be an evaluation on the code to verify if it is valid REGO.

Ensure proto messages are documented

Fields and messages should have godoc comments. Fields should also indicate whether they're required, immutable, or output only (i.e., managed by Rode).

See the discussion here: #113 (comment)

Configure recovery middleware

Currently, a nil pointer in one of the gRPC handlers can crash the entire Rode server. We should configure the grpc_recovery interceptors to prevent that.

An example of configuring the middleware.

Update to Go 1.17

Go 1.17 was released in mid August, might as well upgrade so we don't fall too far behind

Here's list of repositories that we'll want to update. I excluded a few collectors that aren't fully implemented. I'm going to track all of these in a single issue for convenience:

• collector-build (rode/collector-build#16)
• collector-harbor (rode/collector-harbor#21)
• collector-sonarqube (rode/collector-sonarqube#20)
• collector-tfsec (rode/collector-tfsec#8)
• create-build-occurrence-action (rode/create-build-occurrence-action#6)
• enforcer-action (rode/enforcer-action#12)
• enforcer-k8s (rode/enforcer-k8s#24)
• es-index-manager (rode/es-index-manager#12)
• grafeas-elasticsearch (rode/grafeas-elasticsearch#97)
• new-collector-template (rode/new-collector-template#8)
• terraform-provider-rode (rode/terraform-provider-rode#30)
• rode (#145)

Formatting on policy evaluation messages

This could be something that needs to be handled in the policy itself, but could Rode do something to handle fields that are being set (or not set in the case of failure here) in the evaluation? Just reads a little weird as an end user.

handle build occurrence artifacts when creating resources

we probably need to treat build occurrences differently in BatchCreateResources

Right now sending a build occurrence will only create a Git resource, but any artifacts will produce versions tied to a parent that doesn't exist.

Originally posted by @alexashley in #76 (comment)

Add ListGenericResources endpoint

Name TBD. The ListResources RPC does a collapse on an occurrence's resource.uri field, returning unique resource.uris. This isn't particularly helpful when trying to present a list of Docker images or NPM packages to a user in rode-ui, since they will see every single version of that image or package.

This ListGenericResources endpoint would return only the unique set of names across all resources. We could do this by tracking those as a separate document type.

Return additional policy information on endpoints

The UI displays the policy name and links to the policy when viewing policy group assignments and resource evaluations. Because the current endpoints only return the policyVersionId, anytime the user navigates to those particular views there are additional calls needed to go fetch the policy data.

The additional data I would like to see included are

• policy name
• policy version
• policy ID

Policy version and policy ID can be derived from policyVersionId, but if the structure of a policyVersionId changes in the future, the UI would break.

Endpoints to add additional policy data

• /resource-evaluations?resourceUri=${resourceUri}
• /policy-groups/${policyGroupName}/assignments

Update ListResources query to include aggregations

See #60 (comment) for more context

Add fuzzing tests

Rode is configured to recover on panics in individual RPCs, but we should incorporate some fuzzing

Built-in fuzzing support should be landing Go 1.18, but it can also be used directly now: https://pkg.go.dev/testing@master#hdr-Fuzzing

Doesn't look like this would mesh well with Ginkgo.

Update policy validation to also check that violations.result includes 'message' and 'pass'

Currently the validation checks to see that a pass block and violations block returning a result object exists.
Confirm that the result block also contains a pass key and message key

Authorization interceptor

Add a gRPC interceptor to check permissions on RPC calls. This will require changes to the JWT and basic authentication interceptors in order to set roles.

Policy Search is case sensitive

Searching for a a policy is case sensitive, but in my opinion should not be.

implement RPCs for getting and listing evaluations

implement get, list for resource evaluations. support filtering on list RPC

optimize code path for BatchCreateOccurrences

see original discussion here: #76 (comment)

we should either revert these path changes, or pre-populate the CreateTime for each occurrence if it is not already set.

Fetching resource evaluations for resource that has not been evaluated

Calling the endpoint /v1alpha1/resource-evaluations?resourceUri=${uriHere} for a resource that has not been evaluated.

I would have expected the endpoint to return an empty array or maybe a 404, but instead I get this error message.

{
    "code": 13,
    "message": "error searching for policy evaluations: unexpected response from elasticsearch: [400 Bad Request] {\"error\":{\"root_cause\":[{\"type\":\"parse_exception\",\"reason\":\"request body or source parameter is required\"}],\"type\":\"parse_exception\",\"reason\":\"request body or source parameter is required\"},\"status\":400}",
    "details": []
}

Update development instructions

We reference these development docs in the README, which instruct contributors to use skaffold for local development. However, the version of the Rode Helm chart used by skaffold is out of date and we largely don't use skaffold for local development currently.

We should devise a better local developer experience and document that.

RegisterCollector: create notes

a new RPC needs to be added to allow collectors to create notes that they will reference in any occurrences they send to rode. this will allow different collectors that both use the same occurrence type to be differentiated in the UI when the occurrences are displayed to the user.

Explore embedding the OPA library

We call out to an external OPA server for policy evaluation; however, we could also embed it as a Go library.

create protos for PolicyGroup, PolicyAssignment

Policy Group

• Name: ID of the policy group - cannot be changed in the UI once created
• Description:

Policy Assignment
(/policies/policyId/assignments/environmentId/resourceType OR
/environments/environmentId/assignments)

• Policy Group name
• Policy Version: Document ID - Reference to policy version document ID

Errors when calling rode when no occurrences exist

When no occurrences/resources exist, some unexpected errors occur when calling the rode api. The UI is handling this okay, but it would be nice for these calls to return empty arrays when the calls are successful but there is no data to return.

When hitting the endpoint /resources or /resources?filter="resource.uri".contains("searchTerm"), you receive this error response.

{
    "code": 2,
    "message": "error occurred during ES query [400 Bad Request] {\"error\":{\"root_cause\":[{\"type\":\"illegal_argument_exception\",\"reason\":\"no mapping found for `resource.uri` in order to collapse on\"}],\"type\":\"search_phase_execution_exception\",\"reason\":\"all shards failed\",\"phase\":\"query\",\"grouped\":true,\"failed_shards\":[{\"shard\":0,\"index\":\"grafeas-v1beta1-rode-occurrences\",\"node\":\"F2RmoEXdTTmLMrJmmKT95A\",\"reason\":{\"type\":\"illegal_argument_exception\",\"reason\":\"no mapping found for `resource.uri` in order to collapse on\"}}],\"caused_by\":{\"type\":\"illegal_argument_exception\",\"reason\":\"no mapping found for `resource.uri` in order to collapse on\",\"caused_by\":{\"type\":\"illegal_argument_exception\",\"reason\":\"no mapping found for `resource.uri` in order to collapse on\"}}},\"status\":400}",
    "details": []
}

The rode logs do not show any errors from this call.

---

When hitting the endpoint /occurrences or /occurrences?filter="resource.uri"=="resourceUriGoesHere", you receive this error response.

{
    "code": 13,
    "message": "list occurrences failed",
    "details": []
}

Rode logs this error as well.

list occurrences failed	{"error": "rpc error: code = Internal desc = unexpected response from elasticsearch", "filter": ""}

rename GenericResource, GenericResourceVersion -> Resource, ResourceVersion

rename protos and URIs to remove the "generic" qualifier. this will be a breaking change

Convert all test suites to Ginkgo

The following packages have test suites that use the standard library; however the majority of tests use ginkgo. For the sake of consistency and easier onboarding, these test suites should be migrated.

• auth
• config

ListGenericResourceVersions by specifying a versioned resource uri

If I could pass a resourceUri (the versioned resource identifier) to the endpoint to listGenericResourceVersions and receive the same payload that exists today, that would remove the need for the UI to recalculate the id currently used in that endpoint.

This is important for when a user lands directly on an endpoint for a versioned resource - there's currently no way to get the related versions without the UI recalculating the id or making multiple api calls to get the id and then get the related versions.

implement EvaluateResource RPC

EvaluateResource

• Inputs
  • Resource URI
  • Environment id
  • Source
    • Name
    • URL
• Outputs
  • Resource Evaluation Document
  • List of PolicyResult documents

Search Generic Resource by a specific version

During the UI dicussion on 6/3, I tried searching for a resource by the sha of a docker image, but that is no longer available with the listGenericRersource endpoint. Is it possible to add some sort of filtering on this endpoint to specify a version so anyone coming from a git resource, for example, could find the specific resource by the version only

Updating policy needs to populate to OPA

Scenario
Policy A exists in Rode.
You evaluate Policy A through the Rode API or through the Policy Playground.
Through the call to evaluate, Policy A gets loaded into OPA.
Later, you update Policy A's rego code.
You evaluate Policy A through the Rode API or through the Policy Playground.
Because the policy already exists in OPA, the evaluation is done on the old version of Policy A.

This is causing some weird behavior in the UI especially, since we show the Rego code of a policy at evaluation time but the evaluation being done in OPA is actually against an older version of the policy.

See this slack thread for discovery of this bug

RPCs for PolicyAssignments

CRUD PolicyAssignments (update is policy version only)
ListPolicyAssignments (list by policy id)

RegisterCollector: update / version notes

at some point, collectors might want to update or create new versions of notes that they reference when creating occurrences.

example: perhaps the harbor collector populates its DISCOVERY note with the version of harbor and the version of trivy that's performing the scan. if harbor / trivy updates, we may want to change the information stored in the note to reflect this.

• if we update the note, existing occurrences that reference this note would also see their data changed in the UI. example: DISCOVERY occurrences that were created in the past and scanned with an older version would reference a newer version if that information is exposed via the note it references, and this note is updated. we probably don't want to do this.
• if we version the note, rode would have to know when to create a new note vs reusing an existing one, but this would mean that occurrences that were created in the past by older versions of harbor / trivy wouldn't be changed when they're displayed in the UI.

EvaluatePolicy should use related occurrences populated from build, not just occurrences for the resource

The EvaluatePolicy RPC should follow the same logic as ListVersionedResourceOccurrences to ensure that occurrences for the given resource URI and related occurrences fetched via the build are all sent to OPA for policy evaluation.

Add DeletePolicyGroup RPC

Allow for deleting policy groups. This would be a soft delete, similar to how Rode handles policy deletion

RPCs for PolicyGroups

CRU PolicyGroups (update is description only)
ListPolicyGroups

Test out additional authentication providers

• AzureAD

Update ListResources/ListGenericResources to sort by "newest"

The endpoint should return the list sorted by the resource's creation time. I'm assuming this should just be by whatever is the oldest occurrence created timestamp but this is up for discussion.

See this slack convo for details

create models for ResourceEvaluation, PolicyResult

Resource Evaluation

• Overall “pass” or “fail” when ANDing each policy result
• Datetime (created)
• Source
  • Name: Source of policy evaluation (GitHub Action, K8s enforcer)
  • URL: (optional) URL to logs for the event (i.e. GitHub Action etc) that triggered policy evaluation.
• Resource Version (embed)
  • Id
  • Type
  • Name
  • Version (resourceUri)
• Environment (the id which is also its name)

Policy Result

• Overall “pass” or “fail” when ANDing each rule
• Parent: Resource Evaluation reference
• Policy Version ID
• Result {} (not explanation)

Prevent policy assignments where the policy or policy group has been deleted

CreatePolicyAssignment and UpdatePolicyAssignment should both disallow this.

Add pagination to Rode

All list endpoints should have pagination implemented

add type information for generic resources

generic resources should include a type field that can be used to filter on.

todo:

• update the index for generic resources to include this new field
• update BatchCreateOccurrences to populate this field when creating generic resources
• update ListGenericResources to include a filter that can be used to exclude / include certain types