socket scan

You can create a Scan, view a Scan, view the diff of two scans, and get a report relative to your organization's security policy and license policy.

Scan related commands

  Usage
    $ socket scan <command>

  Commands
    create            Create a scan
    del               Delete a scan
    list              List the scans for an organization
    metadata          Get a scan's metadata
    report            Check whether a scan result passes the organizational policies
                      (security, license)
    view              View the raw results of a scan

  Options
    --help            Print this help

  Examples
    $ socket scan --help

To create a new Scan on a given project folder, run socket scan create on that folder. Without further arguments it should ask you to confirm the organization and whether you want to use the current directory. In subsequent runs it should give you an example of how to run the same command without interactive prompts, something like socket scan create beardev .. You can also set the repository name, the branch name, whether this is the default branch, and whether this Scan should show up on your dashboard at all.

You can get a list of latest Scans made in your organization through socket scan list.

Given a Scan ID you can;

• Delete it (socket scan delete)
• View a fairly raw representation of it (socket scan view)
• View a report of it (socket scan report)
• Get the metadata from a report (socket scan metadata).

Note that these commands support

• --json for a raw payload (which you can forward to jq)
• --markdown for easy sharing

Creating Scans

One of the most used commands in the CLI is the command to create a new Scan. This is necessary to view a health report on your current repository / branch. The main command is socket scan create which currently requires your org name (slug) and the target directory, usually that's just a dot (.) to signify the current directory. You can give any path or glob pattern.

You can also tell it to which repository or branch the new Scan belongs;

• --repo tells Socket to which repository this Scan belongs (default: socket-default-repository)
• --branch tells Socket to which branch this Scan belongs (default: socket-default-branch)

Repo names are required to follow these rules:

• Only a-z A-Z 0-9 and ., _, and - are allowed
• Max length is 100

Branch names are required to follow these rules, which should be roughly equal to GitHub's branch names:

• be 1–255 characters long
• cannot be exactly @ or 0
• cannot begin or end with /, ., or .lock
• cannot contain //, .., @{, any control characters, spaces, or any of ; ~ ^ : ? * [ .

The --report flag will immediately wait for the results and print a report once that's done. This may take some time depending on the complexity of your Scan.

Alternatively you can take the resulting Scan ID (which is returned immediately even if the Scan is not finished yet) and pass it on to socket scan report.

Automation

Here is an automation example of running it as part of your CI logic;

socket scan create \
  --report \
  --repo="$CI_PROJECT_NAME" \
  --branch="$CI_COMMIT_REF_NAME" \
  $SOCKET_ORG_NAME .

(Note: this example ends with a dot.) This will create the scan on the current directory, wait for the report, and have exit code 0 for success or 1 if the Scan does not pass your security policy or license policy (or if an error occurred).

Make sure you set the env vars to the appropriate values. For example, GitLab should expose the CI_PROJECT_NAME variable. Each environment will have their own set of env vars exposed.