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
-
Command-line flags
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.
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.
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 "..."