SOOS Core SCA for Circle CI

SOOS is an independent software security company, located in Winooski, VT USA, building security software for your team. SOOS, Software security, simplified.

Use SOOS to scan your software for vulnerabilities and open source license issues with SOOS Core SCA. Generate and ingest SBOMs. Export reports to industry standards. Govern your open source dependencies. Run the SOOS DAST vulnerability scanner against your web apps or APIs. Scan your Docker containers for vulnerabilities. Check your source code for issues with SAST Analysis.

Demo SOOS or Register for a Free Trial.

If you maintain an Open Source project, sign up for the Free as in Beer SOOS Community Edition.

soos-ci-analysis-circleci-orb

A CircleCI Orb for using SOOS to check for vulnerabilities in your projects.

Example usage:

version: 2.1

orbs:
  soos: soos-io/sca@x.y.z

#
# The Workflow is the example of how a user would integrate with the SOOS Orb
#
workflows:
  main:
    jobs:

      - soos/analysis_async_init:
          client_id: "<<SOOS Client Id>>"
          api_key: "<<SOOS API Key>>"

      - soos/analysis_async_result:
          client_id: "<<SOOS Client Id>>"
          api_key: "<<SOOS API Key>>"

          requires:
           - soos/analysis_async_init
        

The SOOS Action has properties which are passed to the action using with.

Property	Default	Description
client_id		SOOS Client ID - get yours from SOOS Integration. Uses SOOS_API_CLIENT env value if present.
api_key		SOOS API Key - get yours from SOOS Integration. Uses SOOS_API_KEY env value if present.
branch_name	CIRCLE_BRANCH	Branch Name to create scan under
build_version		Version of application build artifacts.
on_failure	continue_on_failure	Flag indicating whether or not to return an error code if errors are found in the SOOS script or SOOS analysis.
output_format		Output format for vulnerabilities: only the value SARIF is available at the moment
directories_to_exclude		Listing of directories or patterns to exclude from the search for manifest files. eg: bin/start/, /start/
files_to_exclude		Listing of files or patterns patterns to exclude from the search for manifest files. eg: /req.txt/, **/requirements.txt
package_managers		List (comma separated) of Package Managers to filter manifest search. (Dart, Erlang, Homebrew, PHP, Java, Nuget, NPM, Python, Ruby, Rust.)
log_level	INFO	Log level to show: DEBUG, INFO, WARN, FAIL, ERROR.

The SOOS Action has environment variables which are passed to the action using env. These environment variables are stored as project environment variables and are required for the action to operate.

Property	Description
SOOS_PROJECT_NAME	A custom project name that will present itself as a collection of test results within your soos.io dashboard.
SOOS_BASE_URI	The API BASE URI provided to you when subscribing to SOOS services.
SOOS_ROOT_CODE_PATH	The relative path from the workspace to search for manifest files to analyze.
SOOS_CLIENT_ID	Provided to you when subscribing to SOOS services.
SOOS_API_KEY	Provided to you when subscribing to SOOS services.

EXAMPLE: Asynchronous scan that contains other CI logic between the two SOOS jobs:

version: 2.1

orbs:
  soos: soos-io/sca@1.0.0

workflows:
  main:
    jobs:

      # NOTE: YOUR OTHER JOBS GO HERE

      - soos/analysis_async_init:
          client_id: "<<SOOS Client Id>>"
          api_key: "<<SOOS API Key>>"

      # NOTE: YOUR OTHER JOBS GO HERE

      - soos/analysis_async_result:
          client_id: "<<SOOS Client Id>>"
          api_key: "<<SOOS API Key>>"

          # NOTE: RUNNING ASYNCHRONOUSLY WILL REQUIRE A DEPENDENCY TO BE ESTABLISHED AGAINST THE "analysis_async_init" JOB
          requires:
           - soos/analysis_async_init

        # NOTE: YOUR OTHER JOBS GO HERE
        

ENVIRONMENT VARIABLES FOR THE ABOVE EXAMPLE

Property	Value
SOOS_PROJECT_NAME	"My Project Name"
SOOS_BASE_URI	"https://api.soos.io/api/"
SOOS_ROOT_CODE_PATH	"./"
SOOS_CLIENT_ID	[redacted]
SOOS_API_KEY	[redacted]

EXAMPLE: Synchronous scan that continues running until analysis complete or timeout reached:

version: 2.1

orbs:
  soos: soos-io/sca@x.x.x

workflows:
  main:
    jobs:

      # NOTE: YOUR OTHER JOBS GO HERE

      - soos/analysis_run_and_wait:
          client_id: "<<SOOS Client Id>>"
          api_key: "<<SOOS API Key>>"

      # NOTE: YOUR OTHER JOBS GO HERE
      

ENVIRONMENT VARIABLES FOR THE ABOVE EXAMPLE

Property	Value
SOOS_PROJECT_NAME	"My Project Name"
SOOS_BASE_URI	"https://api.soos.io/api/"
SOOS_ROOT_CODE_PATH	"./"
SOOS_CLIENT_ID	[redacted]
SOOS_API_KEY	[redacted]

EXAMPLE: "Fire and Forget" scan that runs and the analysis result is inconsequential to the CI build.

version: 2.1

orbs:
  soos: soos-io/sca@x.x.x

workflows:
  main:
    jobs:

      # NOTE: YOUR OTHER JOBS GO HERE

      - soos/analysis_async_init:
          client_id: "<<SOOS Client Id>>"
          api_key: "<<SOOS API Key>>"

      # NOTE: YOUR OTHER JOBS GO HERE
      

ENVIRONMENT VARIABLES FOR THE ABOVE EXAMPLE

Property	Value
SOOS_PROJECT_NAME	"My Project Name"
SOOS_BASE_URI	"https://api.soos.io/api/"
SOOS_ROOT_CODE_PATH	"./"
SOOS_CLIENT_ID	[redacted]
SOOS_API_KEY	[redacted]

How to Publish An Update

1. Merge pull requests with desired changes to the main branch.
   • For the best experience, squash-and-merge and use Conventional Commit Messages.
2. Find the current version of the orb.
   • You can run circleci orb info soos-io/sca | grep "Latest" to see the current version.
3. Create a new Release on GitHub.
   • Click "Choose a tag" and create a new semantically versioned tag. (ex: v1.0.0)
     • We will have an opportunity to change this before we publish if needed after the next step.
4. Click "+ Auto-generate release notes".
   • This will create a summary of all of the merged pull requests since the previous release.
   • If you have used Conventional Commit Messages it will be easy to determine what types of changes were made, allowing you to ensure the correct version tag is being published.
5. Now ensure the version tag selected is semantically accurate based on the changes included.
6. Click "Publish Release".
   • This will push a new tag and trigger your publishing pipeline on CircleCI.