Repository Scan

The Styra DAS Repository Scan System is a special System that scans existing Kubernetes or Terraform configuration files stored in a Git repository hosted on a Git provider such as GitHub, Bitbucket, or Azure Git and analyzes the repository for risks. After Repo Scan analyzes the repository, Styra DAS generates a compliance report using policy libraries that identify best practice violations.

note

When you create a Repository Scan (Repo Scan) System through the Styra DAS UI, GitHub is the only Git provider that can be configured. Use the Styra DAS API to configure other Git repositories.

When you use Repo Scan, a new System is created that links to that library code and can be run against your Git repository.

Repository Access

Repo Scan requires OAuth 2.0 access to GitHub repositories. The selected repositories are cloned as a short-term process. Rules are run against a GitHub repository using an Open Policy Agent (OPA).

note

In order to use Repo Scan with other Git providers (for example BitBucket or Azure Git) refer to creating a Repo Scan System with the API

Repo Scan does not run analytics on your repository and does not store your code beyond the process used to generate your compliance results.

To remove the GitHub access granted to Repo Scan, go to the GitHub applications page, find the "Styra DAS" entry, and use "Revoke Entry" from the context menu.

Using a Sample Repository

You can test Repo Scan with a public repository, provided by Styra. This option allows you to select "Public repositories" as opposed to "Public and private repositories". The sample repository is Repo Scan.

Repo Scan Results

After Repo Scan completes, it opens the compliance view of your new System and displays a list of any identified violations. You can see further details about any violation by selecting a row in the list, which opens a details view. Within the details view, you can further drill down to the policy that flagged the violation through a hyperlink on the rule path.

Creating a Repository Scan System through the Styra DAS UI

Use the following steps to create a Repository Scan System through the Styra DAS UI to analyze a GitHub repository for risks.

1. Login to the Styra DAS UI.
2. In System, click the Add button. The Create System dialog box appears.
3. For System Type, select Repository System.
4. Type in the System name.
5. (Optional) Type the description for the system.
6. For Launch Quick Start leave the toggle configured for No.
7. Expand Advanced.
8. For Show Errors leave the toggle configured for Yes.
9. For Read-only leave the toggle configured for No.
10. In Git Repository (required) click Select Repository. The Select GitHub repository scope pane appears.
11. Select your GitHub repository scope, Public and private repositories (recommended) or Public repositories.
12. Click Continue.
13. The first time you create a Repository Scan System, the Authorize Styra DAS dialog box appears, click Authorize StyraInc. The Choose a repository to scan pane appears.
14. Select any repository off of the main (or master) branch with existing Kubernetes or Terraform configuration files.
15. Click Confirm Selection.
16. (Optional) Configure the GitHub Reference.
17. (Optional) Configure the GitHub Repository Path.
18. By default the Secrets API Credentials Path is configured based on the credentials accessed when Authorize StyraInc is configured.
19. Click Create System. A progress bar appears as the Styra DAS System is created and the repository is scanned. The setup and scan typically takes 30 to 45 seconds. Once complete, The Styra DAS UI automatically switches over to the Compliance tab of your newly created Repo Scan System, and displays a list of any violations.
20. (Optional) If violations are discovered, review each violation and if warranted, make changes in your repository to resolve the violation. Commit the changes to your repository.
21. (Optional) Click Scan Again to rescan the repository to confirm any changes are resolved.

Deleting a Repo Scan System

To delete a Repo Scan System complete the following steps.

1. Login to Styra DAS.
2. In Systems select your Repo Scan System.
3. Click the kebab icon.
4. Click Delete System. A confirmation dialog box appears.
5. Type in the name of the System to delete.
6. Click Delete.

Creating a Repository Scan System with the Styra DAS API

Use the following steps to create a Repository Scan System through the Styra DAS UI to analyze a GitHub or another Git provider repository (for example Bitbucket or Azure Git) for risks.

note

The API calls described in this section require Styra DAS API token. Refer API token Permissions to manage API tokens for Styra DAS.

There are two steps to creating a Repo Scan System using the API:

1. Create a Styra DAS Secret with the Access Token provided by the Git provider.
2. Create a Repo Scan System using the repositories location and the path to the Styra DAS secret.

Create a Styra DAS Secret with the OAuth2 Access Token

1. Obtain an Access Token from your Git provider

Styra recommends to use a GitHub Personal Access Token. A token can be generated at github.com/settings/token or by clicking through the profile-picture and navigating to Settings >> Developer Settings >> Personal access tokens.

Perform the equivalent steps for your selected Git provider and obtain an access token.

• Bitbucket App Passwords
• Azure Git Access Tokens

2. Store the Access Token as a Secret in Styra DAS

export DAS_ID="alice.styra.com"             # the tenant URL of SaaS Styra DAS or a self-hosted URL
export DAS_API_TOKEN="abcdefg"              # this is generated in the workspace admin settings
export REPOSITORY_NAME="my-code-repository" # the repository's name or a unique id to distinguish the secret
export REPOSITORY_URL="..."                 # URL for cloning the repository

curl -X PUT "https://${DAS_ID}/v1/secrets/git/${REPOSITORY_NAME}-scan-access" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${DAS_API_TOKEN}" \
  --data-raw '
{
    "name": "git-user-name",
    "description": "access token for repository scanning",
    "secret": "token value"
}'

Where,

• git/${REPOSITORY-NAME}-scan-access is the id of the secret. You can change the id as you see fit. This id is used in the next step.
• name is the Git user id.
• description stores any useful information describing token.
• secret is a password or token for that user. It is sufficient for the credentials given here to have Read access to the Git repository.

For more Git Authentication Options refer configure Git Authentication

Create a Repo Scan System with the API

1. Create a System with the following API call.

curl -X POST "https://${DAS_ID}/v1/systems" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${DAS_API_TOKEN}" \
  --data-raw "
{
  \"name\": \"any name of your choice\",
  \"description\": \"a non-Github Repo Scan System\",
  \"type\": \"template.reposcan:1.0\",
  \"type_parameters\": {
    \"repositoryURL\": \"${REPOSITORY_URL}\",
    \"credentials\": \"git/${REPOSITORY_NAME}-scan-access\",
    \"reference\": \"refs/heads/main\"
  }
}
"

Where,

• Within the type_parameters object, the field repositoryURL is the URL of the Git repository.
• credentials is a reference to the secret created in the first step.
• reference is the git branch that should be scanned.

Once created, the System can be viewed in Styra DAS UI using the result.id returned as part of the response of the creation request. For reference, the compliance view for a System can be accessed at the following path in the Styra DAS UI:

https://{DAS_ID}/systems/{SYSTEM_ID}/compliance