Skip to content

Using Sinistral with CI

The Sinistral CLI can be used non-interactively for CI by using either Project Credentials or Organization Credentials. You will need to at least provide the api_url and auth_url config in addition to the credentials. More info on configuring the CLI can be found in Configuring the CLI.

Providing Credentials

The recommended way to provide credentials is to use your CI system's secrets management, via either environment variables or CLI parameters.

For example:

  • Environment variables

    export SINISTRAL_API_URL="https://api-url/"
    export SINISTRAL_AUTH_URL="https://auth-url/"
    export SINISTRAL_PROJECT_CLIENT_ID="xxx"
    export SINISTRAL_PROJECT_CLIENT_SECRET="yyy"
    

  • Command-line flags

    sinistral --api-url "https://api-url/" --auth-url "https://auth-url/" --project-client-id "xxx" --project-client-secret "yyy login"
    

Project Credentials Auth Flow

Project Credentials are used by the CLI with CI systems to programmatically create and upload scans for a specific project. They are created automatically when a Project is added, and can be accessed or regenerated either via the UI or via the CLI.

Project Credentials in the UI

When logged in as an admin, clicking the (key) button will bring up the Project Credentials dialog:

The credentials can be copied from there, or the Regenerate button can be used to disable the current credentials and create new ones.

Project Credentials in the CLI

You can retrieve or regenerate Project Credentials using the CLI as well. To do so, you must be authenticated as an admin.

sinistral projects get-credentials --name Test
sinistral projects regenerate-credentials --name Test

Both of these will output the credentials:

project_client_id: 4kgkjr81h923mkqck5v0hi09b
project_client_secret: u7cgtiqfi.................................inkoht0g2

Using Project Credentials

Logging in with these credentials will get an access token that will last 1 hour.

Access Token Lifetime

When Project Credentials are Regenerated, creating new access tokens with the old credentials will be immediately disabled but any currently active access tokens will continue to work until their 1 hour lifetime expires.

sinistral --api-url https://sinistral.example.com/ --auth-url https//auth.example.com/ --project-client-id ... --project-client-secret .... login
sinistral projects get --name Test
sinistral scans create --project-name Test --results "..." --status "..."

Organization Credentials Auth Flow

Organization Credentials work similarly to Project Credentials, except that they allow for the creation of new Projects and uploading scan results to any project. They are intended to be used by CI systems where many, or dynamic, projects are needed, so the CI system may need to create the project as well as perform and upload the scan.

Organization Credentials are not automatically created, and must be generated once before use. If regenerated, all users of the credentials will need to update to the new credentials.

Organization Credentials in the UI

When logged in as an admin, under the Settings section of the sidebar is an Organization Credentials link, which opens the Organization Credentials page.

TODO

The UI for Organization Credentials is still in progress.

The credentials can be generated, if they have not been already, or regenerated to disable the current credentials and create new ones.

Organization Credentials in the CLI

You can retrieve or (re)generate Organization Credentials using the CLI as well. To do so, you must be authenticated as an admin.

sinistral org get-credentials
sinistral org regenerate-credentials

Both of these will output the credentials:

org_client_id: 4kgkjr81h923mkqck5v0hi09b
org_client_secret: u7cgtiqfi.................................inkoht0g2

Using Organization Credentials

Logging in with these credentials will get an access token that will last 1 hour.

Access Token Lifetime

When Organization Credentials are Regenerated, creating new access tokens with the old credentials will be immediately disabled but any currently active access tokens will continue to work until their 1 hour lifetime expires.

sinistral --api-url https://sinistral.example.com/ --auth-url https//auth.example.com/ --org-client-id ... --org-client-secret ... login
sinistral projects create --name Test --collections "My Policy Collection" --groups '{"read": ["admin"]}'
sinistral scans create --project-name Test --results "..." --status "..."