@aikidosec/ci-api-client 1.0.5 → 1.0.6

package/.github/workflows/build-and-release.yml

@@ -0,0 +1,40 @@
+name: Build and release
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20.x"
+          registry-url: "https://registry.npmjs.org"
+          scope: "@aikidosec"
+          cache: 'yarn'
+
+      - name: Install dependencies
+        run: yarn install
+
+      - name: Build the library
+        run: yarn build
+
+      - name: Get the version
+        id: get_version
+        run: echo "tag=${GITHUB_REF/refs\/tags\//}" >> $GITHUB_OUTPUT
+
+      - name: Set the version
+        run: npm --no-git-tag-version version ${{ steps.get_version.outputs.tag }}
+
+      - name: Publish to NPM
+        run: |
+          echo "Publishing version ${{ steps.get_version.outputs.tag }} to NPM"
+          npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}

package/README.md

@@ -1,10 +1,11 @@
-# Aikido Security CI API client
+# Aikido Security CI client
 
 <!-- [![NPM Version](http://img.shields.io/npm/v/aikido-api-client.svg?style=flat)](https://www.npmjs.org/package/aikido-api-client)
 [![NPM Downloads](https://img.shields.io/npm/dm/aikido-api-client.svg?style=flat)](https://npmcharts.com/compare/aikido-api-client?minimal=true)
 [![Install Size](https://packagephobia.now.sh/badge?p=aikido-api-client)](https://packagephobia.now.sh/result?p=aikido-api-client) -->
 
-CLI helper for the public [Aikido CI API](https://aikido-dev.notion.site/aikido-dev/Aikido-CI-API-78d318b5f5f7477ab072e12f94b21374). This cli tool can help integrate Aikido into a custom CI pipeline without having to implement the Aikido CI API yourself.
+This CLI tool can help integrate Aikido Security scans into any custom CI pipeline such as Jenkins, CircleCI,... 
+If you are looking to add checks to a Github, Azure Repos,.. pull request, you do not need this package and you can use our native plugins.
 
 ## Installation and setup
 
@@ -26,15 +27,67 @@ $ aikido-api-client apikey <your-api-key-here>
 
 ⚠️ Your Aikido API key is stored in `~/.config/configstore/aikido-api-client.json`. If you don't want this behaviour (e.g. for security related issues), you can also provide your API key to `aikido-api-client` by adding `--apikey <your-api-key-here>` to every command. However, for the examples below, we'll assume you've used `aikido-api-client apikey <your-api-key-here>` to save your API key. If `--apikey` is provided while a key is set in the configuration file on disk, the key that was provided with `--apikey` will be used.
 
-## Usage
+## Use case: release gating
 
-Using the `aikido-api-client` to start new scans is very straightforward.
+The example below shows how to use the `scan-release` command. The use case here is to block a new build or a new release as long as issues are still open.
+
+```sh
+$ aikido-api-client scan-release <repository_id or repository_name> <commit_id>
+```
+```
+Usage: Aikido API Client scan-release [options] <repository_id> <commit_id>
+Run a release scan of an Aikido repo.
+Arguments:
+  repository_id                     The internal GitHub/Gitlab/Bitbucket/.. repository id you want to scan.
+  commit_id                         The commit you want to scan
+Options:
+  --no-fail-on-dependency-scan      Don't fail when scanning depedencies. Default is to fail on new CVE
+  --fail-on-sast-scan               Let Aikido fail when new static code analysis issues have been detected
+  --fail-on-iac-scan                Let Aikido fail when new infrastructure as code issues have been detected
+  --fail-on-secrets-scan            Let Aikido fail when new exposed secrets have been detected
+  --minimum-severity-level <level>  Set the minimum severity level. Accepted options are: LOW, MEDIUM, HIGH and CRITICAL. (choices: "LOW", "MEDIUM",
+                                    "HIGH", "CRITICAL")
+  --poll-interval [interval]        The poll interval when checking for an updated scan result (preset: 10)
+  -h, --help                        display help for command
+```
+
+## Use case: pull request checks & gating
+
+The example below shows how to use the 'scan' command. The use case here is to add a red/green check to a pull request based on the difference in files (head vs base commit).
 
 ```sh
 $ aikido-api-client scan <repository_id or repository_name> <base_commit_id> <head_commit_id>
 ```
+```
+Usage: Aikido API Client scan [options] <repository_id> <base_commit_id> <head_commit_id> [branch_name]
+Run a scan of an Aikido repo.
+Arguments:
+  repository_id                          The internal GitHub/Gitlab/Bitbucket/.. repository id you want to scan.
+  base_commit_id                         The base commit of the code you want to scan (e.g. the commit where you branched from for your PR or the
+                                         initial commit of your repo)
+  head_commit_id                         The latest commit you want to include in your scan (e.g. the latest commit id of your pull request)
+  branch_name                            The branch name (default: "main")
+Options:
+  --pull-request-title <title>           Your pull request title
+  --pull-request-url <url>               Your pull request URL
+  --self-managed-scanners <scanners...>  Set the minimum severity level. Accepted options are: LOW, MEDIUM, HIGH and CRITICAL. (choices: "checkov",
+                                         "json-sbom")
+  --expected-amount-json-sboms <amount>  The expected amount of json sbombs
+  --no-fail-on-dependency-scan           Don't fail when scanning depedencies. Default is to fail on new CVE
+  --fail-on-sast-scan                    Let Aikido fail when new static code analysis issues have been detected
+  --fail-on-iac-scan                     Let Aikido fail when new infrastructure as code issues have been detected
+  --fail-on-secrets-scan                 Let Aikido fail when new exposed secrets have been detected
+  --minimum-severity-level <level>       Set the minimum severity level. Accepted options are: LOW, MEDIUM, HIGH and CRITICAL. (choices: "LOW",
+                                         "MEDIUM", "HIGH", "CRITICAL")
+  --poll-interval [interval]             The poll interval when checking for an updated scan result (preset: 5)
+  -h, --help                             display help for command
+```
+
+
+
+## How it works
 
-The process will report scan progress and will exit with exitCode `0` if the scan was successfull (`gate_passed: true`). The process will exit with exitCode `10` if the scan was unsuccesfull (`gate_passed: false`). If anything else goes wrong (e.g. API unavailable, scanning unavailable, other unexpected issue) the process will exit with exitCode `1`.
+The CLI will spawn a cloud-based scan and then report scan progress. It will exit with exitCode `0` if the scan was successfull (`gate_passed: true`). The process will exit with exitCode `10` if the scan was unsuccesfull (`gate_passed: false`). If anything else goes wrong (e.g. API unavailable, scanning unavailable, other unexpected issue) the process will exit with exitCode `1`.
 
 If you want the scan to run quietly (without output), you can add the `--quiet` option to the command.
 
@@ -43,9 +96,10 @@ Please note that the repository_id which you need to provide to the CLI is the u
 ```sh
 # For more options and combinations, check the help output
 $ aikido-api-client help scan
+$ aikido-api-client help scan-release
 ```
 
-Uploading custom test results:
+Uploading custom test results (supported by the `scan` command only):
 
 ```sh
 $ aikido-api-client upload --repository-id <repository_id> --type checkov --file <path_to_payload_file>
@@ -54,7 +108,7 @@ $ aikido-api-client upload --repository-id <repository_id> --type checkov --file
 $ aikido-api-client help upload
 ```
 
-For more information about these parameters, please refer to `aikido-api-client help`, `aikido-api-client help scan` or `aikido-api-client help upload`, or [the public ci api page](https://aikido-dev.notion.site/aikido-dev/Aikido-CI-API-78d318b5f5f7477ab072e12f94b21374).
+For more information about these parameters, please refer to `aikido-api-client help`, `aikido-api-client help scan`, `aikido-api-client help scan-release` or `aikido-api-client help upload`, or [the public ci api page](https://aikido-dev.notion.site/aikido-dev/Aikido-CI-API-78d318b5f5f7477ab072e12f94b21374).
 
 ## Help & contributing
 
@@ -75,6 +129,9 @@ If you are missing functionality in this cli tool, please feel free to add it. I
 
 - [Aikido Official Website](https://aikido.dev)
 - [Aikido Github Actions Workflow](https://github.com/AikidoSec/github-actions-workflow)
+- [Aikido GitLab CI Integration](https://gitlab.com/aikido-security/gitlab-ci-integration)
+- [Aikido Bitbucket Pipe](https://bitbucket.org/aikido-production/bitbucket-pipe)
+- [Aikido Azure Pipelines](https://marketplace.visualstudio.com/items?itemName=AikidoSecurity.aikido-security-scanner)
 - [Aikido on Twitter](https://twitter.com/AikidoSecurity)
 
 

package/lib/aikidoApi.d.ts

@@ -14,6 +14,7 @@ export type TScanApiOptions = {
     fail_on_secrets_scan?: boolean;
     minimum_severity?: string;
     version: string;
+    is_release_gating?: boolean;
 };
 export type TStartScanResult = {
     scan_id: number;

package/lib/commands/scan.js

@@ -118,7 +118,7 @@ export const scan = async ({ repoId, baseCommitId, headCommitId, branchName, opt
     pollStatus();
 };
 const parseCliOptions = (userCliOptions) => {
-    const apiOptions = { version: '1.0.5' };
+    const apiOptions = { version: '1.0.6' };
     const cliOptions = { pollInterval: 5 };
     if (userCliOptions.pullRequestTitle) {
         apiOptions.pull_request_metadata = {
@@ -185,7 +185,7 @@ export const cliSetup = (program) => program
     .addOption(new Option('--no-fail-on-dependency-scan', "Don't fail when scanning depedencies..."))
     .option('--fail-on-sast-scan', 'Let Aikido fail when new static code analysis issues have been detected...')
     .option('--fail-on-iac-scan', 'Let Aikido fail when new infrastructure as code issues have been detected...')
-    .option('--fail-on-secrets-scan', 'Let Aikido fail when new leaked secrets have been detected...')
+    .option('--fail-on-secrets-scan', 'Let Aikido fail when new exposed secrets have been detected...')
     .addOption(new Option('--minimum-severity-level <level>', 'Set the minimum severity level. Accepted options are: LOW, MEDIUM, HIGH and CRITICAL.').choices(['LOW', 'MEDIUM', 'HIGH', 'CRITICAL']))
     .addOption(new Option('--poll-interval [interval]', 'The poll interval when checking for an updated scan result')
     .preset(5)

package/lib/commands/scanRelease.d.ts

@@ -0,0 +1,35 @@
+import { Command } from 'commander';
+import { TPollIsScanningResult, TPollScanCompletedDefaultBranchResult, TPollScanFeatureBranchCompletedResult, TScanApiOptions } from '../aikidoApi.js';
+type TScanArguments = {
+    repoId: string | number;
+    commitId: string;
+    options: TScanApiOptions;
+    pollInterval: number;
+    onStart?: () => void | null;
+    onStartComplete?: (startResult: any) => void | null;
+    onStartFail?: (error: any) => void | null;
+    onScanStart?: (startResult: TPollIsScanningResult | TPollScanFeatureBranchCompletedResult | TPollScanCompletedDefaultBranchResult) => void | null;
+    onNextPoll?: (pollResult: TPollIsScanningResult | TPollScanFeatureBranchCompletedResult | TPollScanCompletedDefaultBranchResult) => void | null;
+    onScanComplete?: (pollResult: TPollIsScanningResult | TPollScanFeatureBranchCompletedResult | TPollScanCompletedDefaultBranchResult) => void | null;
+    onScanFail?: (error: any) => void | null;
+};
+type TScanUserCliOptions = {
+    pullRequestTitle?: string;
+    pullRequestUrl?: string;
+    selfManagedScanners?: string[];
+    failOnDependencyScan?: boolean;
+    failOnSastScan?: boolean;
+    failOnSecretsScan?: boolean;
+    failOnIacScan?: boolean;
+    minimumSeverityLevel?: string;
+    pollInterval?: number;
+};
+declare function cli(repoId: string, commitId: string, options: TScanUserCliOptions, command: string): Promise<void>;
+export declare const scan: ({ repoId, commitId, options, pollInterval, onStart, onStartComplete, onStartFail, onScanStart, onNextPoll, onScanComplete, onScanFail, }: TScanArguments) => Promise<void>;
+export declare const cliSetup: (program: Command) => Command;
+declare const _default: {
+    cli: typeof cli;
+    cliSetup: (program: Command) => Command;
+    scan: ({ repoId, commitId, options, pollInterval, onStart, onStartComplete, onStartFail, onScanStart, onNextPoll, onScanComplete, onScanFail, }: TScanArguments) => Promise<void>;
+};
+export default _default;

package/lib/commands/scanRelease.js

@@ -0,0 +1,182 @@
+import chalk from 'chalk';
+import { Argument, InvalidArgumentError, Option } from 'commander';
+import { pollScanStatus, startScan, } from '../aikidoApi.js';
+import { getApiKey } from '../configuration.js';
+import { outputError, outputHttpError, outputLog, startSpinner, } from '../output.js';
+async function cli(repoId, commitId, options, command) {
+    const apiKey = getApiKey();
+    if (!apiKey) {
+        outputError('Please set an api key using: aikido-cli apikey <key>');
+    }
+    const { apiOptions, cliOptions } = parseCliOptions(options);
+    let loader;
+    let pollCount = 1;
+    const onStart = () => {
+        loader = startSpinner('Starting Aikido Security release scan');
+    };
+    const onStartComplete = (startResult) => {
+        loader?.succeed(`Aikido Security scan started (id: ${startResult.scan_id})`);
+    };
+    const onNextPoll = () => {
+        if (loader) {
+            loader.text = `Polling for Aikido Security scan to complete (${pollCount})`;
+        }
+        pollCount += 1;
+    };
+    const onScanStart = () => {
+        loader = startSpinner('Waiting for scan to complete');
+    };
+    const onScanComplete = (pollResult) => {
+        if (pollResult.gate_passed === true) {
+            loader?.succeed('Scan completed, no open issues found');
+            if (pollResult.diff_url) {
+                outputLog(chalk.gray(`* Diff url: ${pollResult.diff_url}`));
+            }
+        }
+        else {
+            loader?.fail('Scan completed with issues');
+            if (pollResult.new_issues_found) {
+                outputLog(chalk.gray(chalk.bold('Open issues found: ') + pollResult.new_issues_found));
+            }
+            if (pollResult.issue_links) {
+                outputLog(chalk.gray(pollResult.issue_links
+                    .map((issueLink) => '- ' + issueLink)
+                    .join('\n')));
+            }
+            if (pollResult.diff_url) {
+                outputLog(chalk.gray(`* Diff url: ${pollResult.diff_url}`));
+            }
+            process.exit(10);
+        }
+    };
+    const onFail = (error) => {
+        loader?.fail();
+        if (error.response?.status && error.response?.status === 404) {
+            outputError('Please verify your commit SHA');
+        }
+        else {
+            outputHttpError(error);
+        }
+        process.exit(1);
+    };
+    await scan({
+        repoId,
+        commitId,
+        options: apiOptions,
+        pollInterval: cliOptions.pollInterval,
+        onStart,
+        onStartComplete,
+        onStartFail: onFail,
+        onNextPoll,
+        onScanStart,
+        onScanComplete,
+        onScanFail: onFail,
+    });
+}
+export const scan = async ({ repoId, commitId, options, pollInterval = 10, onStart, onStartComplete, onStartFail, onScanStart, onNextPoll, onScanComplete, onScanFail, }) => {
+    onStart?.();
+    let result = null;
+    try {
+        result = await startScan({
+            is_release_gating: true,
+            head_commit_id: commitId,
+            repository_id: repoId,
+            ...options,
+        });
+        if (result.scan_id) {
+            onStartComplete?.(result);
+        }
+        else {
+            onStartFail?.(result);
+            return;
+        }
+    }
+    catch (error) {
+        onStartFail?.(error);
+        return;
+    }
+    onScanStart?.(result);
+    let pollResult;
+    const pollStatus = async () => {
+        try {
+            pollResult = await pollScanStatus(result.scan_id);
+            if (pollResult.all_scans_completed === false) {
+                onNextPoll?.(pollResult);
+                setTimeout(pollStatus, pollInterval * 1000);
+            }
+            else {
+                onScanComplete?.(pollResult);
+            }
+        }
+        catch (error) {
+            onScanFail?.(error);
+        }
+    };
+    pollStatus();
+};
+const parseCliOptions = (userCliOptions) => {
+    const apiOptions = { version: '1.0.6' };
+    const cliOptions = { pollInterval: 10 };
+    if (userCliOptions.pullRequestTitle) {
+        apiOptions.pull_request_metadata = {
+            ...(apiOptions.pull_request_metadata ?? {}),
+            title: userCliOptions.pullRequestTitle,
+        };
+    }
+    if (userCliOptions.pullRequestUrl) {
+        apiOptions.pull_request_metadata = {
+            ...(apiOptions.pull_request_metadata ?? {}),
+            url: userCliOptions.pullRequestUrl,
+        };
+    }
+    if (userCliOptions.selfManagedScanners) {
+        apiOptions.self_managed_scanners = userCliOptions.selfManagedScanners;
+    }
+    if (userCliOptions.failOnDependencyScan != undefined) {
+        apiOptions.fail_on_dependency_scan = userCliOptions.failOnDependencyScan;
+    }
+    if (userCliOptions.failOnSastScan != undefined) {
+        apiOptions.fail_on_sast_scan = userCliOptions.failOnSastScan;
+    }
+    if (userCliOptions.failOnIacScan != undefined) {
+        apiOptions.fail_on_iac_scan = userCliOptions.failOnIacScan;
+    }
+    if (userCliOptions.failOnSecretsScan != undefined) {
+        apiOptions.fail_on_secrets_scan = userCliOptions.failOnSecretsScan;
+    }
+    if (userCliOptions.minimumSeverityLevel) {
+        apiOptions.minimum_severity = userCliOptions.minimumSeverityLevel;
+    }
+    if (userCliOptions.pollInterval &&
+        (isNaN(userCliOptions.pollInterval) || userCliOptions.pollInterval <= 0)) {
+        outputError('Please provide a valid poll interval');
+    }
+    else if (userCliOptions.pollInterval) {
+        cliOptions.pollInterval = userCliOptions.pollInterval;
+    }
+    return { apiOptions, cliOptions };
+};
+const validateCommitId = (value) => {
+    const testCommitId = (commitId) => commitId.length === 40 && /^[0-9a-f]{40}$/.test(commitId);
+    if (testCommitId(value) === false) {
+        throw new InvalidArgumentError('Please provide a valid commit ID');
+    }
+    return value;
+};
+export const cliSetup = (program) => program
+    .command('scan-release')
+    .addArgument(new Argument('<repository_id>', 'The internal GitHub/Gitlab/Bitbucket/.. repository id you want to scan.').argRequired())
+    .addArgument(new Argument('<commit_id>', 'The commit you want to scan')
+    .argRequired()
+    .argParser(validateCommitId))
+    .addOption(new Option('--no-fail-on-dependency-scan', "Don't fail when scanning depedencies..."))
+    .option('--fail-on-sast-scan', 'Let Aikido fail when new static code analysis issues have been detected...')
+    .option('--fail-on-iac-scan', 'Let Aikido fail when new infrastructure as code issues have been detected...')
+    .option('--fail-on-secrets-scan', 'Let Aikido fail when new exposed secrets have been detected...')
+    .addOption(new Option('--minimum-severity-level <level>', 'Set the minimum severity level. Accepted options are: LOW, MEDIUM, HIGH and CRITICAL.').choices(['LOW', 'MEDIUM', 'HIGH', 'CRITICAL']))
+    .addOption(new Option('--poll-interval [interval]', 'The poll interval when checking for an updated scan result')
+    .preset(10)
+    .argParser(parseFloat))
+    .description('Run a release scan of an Aikido repo.')
+    .action(cli);
+export default { cli, cliSetup, scan };

package/lib/index.js

@@ -4,15 +4,17 @@ import { Command } from 'commander';
 import dotenv from 'dotenv';
 import apiKey from './commands/apiKey.js';
 import scan from './commands/scan.js';
+import scanRelease from './commands/scanRelease.js';
 import upload from './commands/upload.js';
 dotenv.config(process.env.NODE_ENV ? { path: `.env.${process.env.NODE_ENV}` } : {});
 export const program = new Command();
 program
     .name('Aikido API Client')
     .description('CLI api client to easily integrate the Aikido public CI API into custom deploy scripts')
-    .version('1.0.4');
+    .version('1.0.6');
 apiKey.cliSetup(program);
 scan.cliSetup(program);
+scanRelease.cliSetup(program);
 upload.cliSetup(program);
 program
     .option('-q, --quiet', 'Disable console output when executing commands')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikidosec/ci-api-client",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "CLI api client to easily integrate the Aikido public CI API into custom deploy scripts",
   "license": "MIT",
   "author": "Bert Devriese <bert@builtinbruges.com>",
@@ -8,11 +8,11 @@
   "type": "module",
   "main": "lib/index.js",
   "bin": {
-    "aikido-api-client": "./lib/index.js"
+    "aikido-api-client": "lib/index.js"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/AikidoSec/api-client.git"
+    "url": "git+https://github.com/AikidoSec/ci-api-client.git"
   },
   "scripts": {
     "start": "nodemon --watch 'src/**/*.ts' --esm --exec 'ts-node' src/index.ts",

package/src/aikidoApi.ts

@@ -25,6 +25,7 @@ export type TScanApiOptions = {
   fail_on_secrets_scan?: boolean;
   minimum_severity?: string;
   version: string;
+  is_release_gating?: boolean;
 };
 
 export type TStartScanResult = {

package/src/commands/scan.ts

@@ -245,7 +245,7 @@ export const scan = async ({
 const parseCliOptions = (userCliOptions: TScanUserCliOptions) => {
   // Version provided to the API corresponds with the version in package.json
   // of the cli client
-  const apiOptions: TScanApiOptions = { version: '1.0.5' };
+  const apiOptions: TScanApiOptions = { version: '1.0.6' };
   const cliOptions: TScanCliOptions = { pollInterval: 5 };
 
   if (userCliOptions.pullRequestTitle) {

package/src/commands/scanRelease.ts

@@ -0,0 +1,349 @@
+import chalk from 'chalk';
+import { Argument, Command, InvalidArgumentError, Option } from 'commander';
+import { Ora } from 'ora';
+import {
+  TPollIsScanningResult,
+  TPollScanCompletedDefaultBranchResult,
+  TPollScanFeatureBranchCompletedResult,
+  TScanApiOptions,
+  TStartScanResult,
+  pollScanStatus,
+  startScan,
+} from '../aikidoApi.js';
+import { getApiKey } from '../configuration.js';
+import {
+  outputError,
+  outputHttpError,
+  outputLog,
+  startSpinner,
+} from '../output.js';
+
+type TScanArguments = {
+  repoId: string | number;
+  commitId: string;
+  options: TScanApiOptions;
+  pollInterval: number;
+  onStart?: () => void | null;
+  onStartComplete?: (startResult: any) => void | null;
+  onStartFail?: (error: any) => void | null;
+  onScanStart?: (
+    startResult:
+      | TPollIsScanningResult
+      | TPollScanFeatureBranchCompletedResult
+      | TPollScanCompletedDefaultBranchResult
+  ) => void | null;
+  onNextPoll?: (
+    pollResult:
+      | TPollIsScanningResult
+      | TPollScanFeatureBranchCompletedResult
+      | TPollScanCompletedDefaultBranchResult
+  ) => void | null;
+  onScanComplete?: (
+    pollResult:
+      | TPollIsScanningResult
+      | TPollScanFeatureBranchCompletedResult
+      | TPollScanCompletedDefaultBranchResult
+  ) => void | null;
+  onScanFail?: (error: any) => void | null;
+};
+
+type TScanCliOptions = {
+  pollInterval: number;
+};
+
+type TScanUserCliOptions = {
+  pullRequestTitle?: string;
+  pullRequestUrl?: string;
+  selfManagedScanners?: string[];
+  failOnDependencyScan?: boolean;
+  failOnSastScan?: boolean;
+  failOnSecretsScan?: boolean;
+  failOnIacScan?: boolean;
+  minimumSeverityLevel?: string;
+  pollInterval?: number;
+};
+
+async function cli(
+  repoId: string,
+  commitId: string,
+  options: TScanUserCliOptions,
+  command: string
+) {
+
+  const apiKey = getApiKey();
+
+  if (!apiKey) {
+    outputError('Please set an api key using: aikido-cli apikey <key>');
+  }
+
+  // Process command options and group them into apiOptions hash
+  const { apiOptions, cliOptions } = parseCliOptions(options);
+
+  let loader: Ora | null;
+  let pollCount: number = 1;
+
+  // Setup different scan() event handlers
+  const onStart = () => {
+    loader = startSpinner('Starting Aikido Security release scan');
+  };
+
+  const onStartComplete = (startResult: TStartScanResult) => {
+    loader?.succeed(
+      `Aikido Security scan started (id: ${startResult.scan_id})`
+    );
+  };
+
+  const onNextPoll = () => {
+    if (loader) {
+      loader.text = `Polling for Aikido Security scan to complete (${pollCount})`;
+    }
+
+    pollCount += 1;
+  };
+
+  const onScanStart = () => {
+    loader = startSpinner('Waiting for scan to complete');
+  };
+
+  const onScanComplete = (pollResult: any) => {
+    if (pollResult.gate_passed === true) {
+      loader?.succeed('Scan completed, no open issues found');
+      if (pollResult.diff_url) {
+        outputLog(chalk.gray(`* Diff url: ${pollResult.diff_url}`));
+      }
+    } else {
+      loader?.fail('Scan completed with issues');
+
+      if (pollResult.new_issues_found) {
+        outputLog(
+          chalk.gray(
+            chalk.bold('Open issues found: ') + pollResult.new_issues_found
+          )
+        );
+      }
+
+      if (pollResult.issue_links) {
+        outputLog(
+          chalk.gray(
+            pollResult.issue_links
+              .map((issueLink: string) => '- ' + issueLink)
+              .join('\n')
+          )
+        );
+      }
+
+      if (pollResult.diff_url) {
+        outputLog(chalk.gray(`* Diff url: ${pollResult.diff_url}`));
+      }
+
+      process.exit(10);
+    }
+  };
+
+  const onFail = (error: any) => {
+    loader?.fail();
+
+    if (error.response?.status && error.response?.status === 404) {
+      outputError(
+        'Please verify your commit SHA'
+      );
+    } else {
+      outputHttpError(error);
+    }
+
+    process.exit(1);
+  };
+
+  await scan({
+    repoId,
+    commitId,
+    options: apiOptions,
+    pollInterval: cliOptions.pollInterval,
+    onStart,
+    onStartComplete,
+    onStartFail: onFail,
+    onNextPoll,
+    onScanStart,
+    onScanComplete,
+    onScanFail: onFail,
+  });
+}
+
+export const scan = async ({
+  repoId,
+  commitId,
+  options,
+  pollInterval = 10,
+  onStart,
+  onStartComplete,
+  onStartFail,
+  onScanStart,
+  onNextPoll,
+  onScanComplete,
+  onScanFail,
+}: TScanArguments): Promise<void> => {
+  onStart?.();
+
+  let result: any | null = null;
+
+  // Initialize a scan and call onStartComplete, onStartFail
+  // handlers where needed
+  try {
+
+    result = await startScan({
+      is_release_gating: true,
+      head_commit_id: commitId,
+      repository_id: repoId,
+      ...options,
+    });
+
+    if (result.scan_id) {
+      onStartComplete?.(result);
+    } else {
+      onStartFail?.(result);
+      return;
+    }
+  } catch (error) {
+    onStartFail?.(error);
+    return;
+  }
+
+  onScanStart?.(result);
+  let pollResult;
+
+  // Poll status with a setTimeout
+  const pollStatus = async () => {
+    try {
+      pollResult = await pollScanStatus(result.scan_id);
+
+      // If "all_scans_completed" returns true, call the onScanComplete
+      // handler, if not, re poll with `pollInterval`
+      // Note that onScanComplete can return a successfull or
+      // unsuccessfull scan result
+      if (pollResult.all_scans_completed === false) {
+        onNextPoll?.(pollResult);
+        setTimeout(pollStatus, pollInterval * 1000);
+      } else {
+        onScanComplete?.(pollResult);
+      }
+    } catch (error) {
+      onScanFail?.(error);
+    }
+  };
+
+  // Start polling
+  pollStatus();
+};
+
+const parseCliOptions = (userCliOptions: TScanUserCliOptions) => {
+  // Version provided to the API corresponds with the version in package.json
+  // of the cli client
+  const apiOptions: TScanApiOptions = { version: '1.0.6' };
+  const cliOptions: TScanCliOptions = { pollInterval: 10 };
+
+  if (userCliOptions.pullRequestTitle) {
+    apiOptions.pull_request_metadata = {
+      ...(apiOptions.pull_request_metadata ?? {}),
+      title: userCliOptions.pullRequestTitle,
+    };
+  }
+  if (userCliOptions.pullRequestUrl) {
+    apiOptions.pull_request_metadata = {
+      ...(apiOptions.pull_request_metadata ?? {}),
+      url: userCliOptions.pullRequestUrl,
+    };
+  }
+  if (userCliOptions.selfManagedScanners) {
+    apiOptions.self_managed_scanners = userCliOptions.selfManagedScanners;
+  }
+  if (userCliOptions.failOnDependencyScan != undefined) {
+    apiOptions.fail_on_dependency_scan = userCliOptions.failOnDependencyScan;
+  }
+  if (userCliOptions.failOnSastScan != undefined) {
+    apiOptions.fail_on_sast_scan = userCliOptions.failOnSastScan;
+  }
+  if (userCliOptions.failOnIacScan != undefined) {
+    apiOptions.fail_on_iac_scan = userCliOptions.failOnIacScan;
+  }
+  if (userCliOptions.failOnSecretsScan != undefined) {
+    apiOptions.fail_on_secrets_scan = userCliOptions.failOnSecretsScan;
+  }
+  if (userCliOptions.minimumSeverityLevel) {
+    apiOptions.minimum_severity = userCliOptions.minimumSeverityLevel;
+  }
+  if (
+    userCliOptions.pollInterval &&
+    (isNaN(userCliOptions.pollInterval) || userCliOptions.pollInterval <= 0)
+  ) {
+    outputError('Please provide a valid poll interval');
+  } else if (userCliOptions.pollInterval) {
+    cliOptions.pollInterval = userCliOptions.pollInterval;
+  }
+
+  return { apiOptions, cliOptions };
+};
+
+const validateCommitId = (value: string) => {
+  const testCommitId = (commitId: string): boolean =>
+    commitId.length === 40 && /^[0-9a-f]{40}$/.test(commitId);
+
+  if (testCommitId(value) === false) {
+    throw new InvalidArgumentError('Please provide a valid commit ID');
+  }
+
+  return value;
+};
+
+export const cliSetup = (program: Command) =>
+  program
+    .command('scan-release')
+    .addArgument(
+      new Argument(
+        '<repository_id>',
+        'The internal GitHub/Gitlab/Bitbucket/.. repository id you want to scan.'
+      ).argRequired()
+    )
+    .addArgument(
+      new Argument(
+        '<commit_id>',
+        'The commit you want to scan'
+      )
+      .argRequired()
+      .argParser(validateCommitId)
+    )
+    .addOption(
+      new Option(
+        '--no-fail-on-dependency-scan',
+        "Don't fail when scanning depedencies..."
+      )
+    )
+    .option(
+      '--fail-on-sast-scan',
+      'Let Aikido fail when new static code analysis issues have been detected...'
+    )
+    .option(
+      '--fail-on-iac-scan',
+      'Let Aikido fail when new infrastructure as code issues have been detected...'
+    )
+    .option(
+      '--fail-on-secrets-scan',
+      'Let Aikido fail when new exposed secrets have been detected...'
+    )
+    .addOption(
+      new Option(
+        '--minimum-severity-level <level>',
+        'Set the minimum severity level. Accepted options are: LOW, MEDIUM, HIGH and CRITICAL.'
+      ).choices(['LOW', 'MEDIUM', 'HIGH', 'CRITICAL'])
+    )
+    .addOption(
+      new Option(
+        '--poll-interval [interval]',
+        'The poll interval when checking for an updated scan result'
+      )
+        .preset(10)
+        .argParser(parseFloat)
+    )
+    .description('Run a release scan of an Aikido repo.')
+    .action(cli);
+
+export default { cli, cliSetup, scan };

package/src/index.ts

@@ -4,6 +4,7 @@ import { Command } from 'commander';
 import dotenv from 'dotenv';
 import apiKey from './commands/apiKey.js';
 import scan from './commands/scan.js';
+import scanRelease from './commands/scanRelease.js';
 import upload from './commands/upload.js';
 
 // Load all .env configuration variables and auto-inject them into process.env
@@ -19,11 +20,12 @@ program
   .description(
     'CLI api client to easily integrate the Aikido public CI API into custom deploy scripts'
   )
-  .version('1.0.4');
+  .version('1.0.6');
 
 // Load in all app commands and set them up in the `program` instance
 apiKey.cliSetup(program);
 scan.cliSetup(program);
+scanRelease.cliSetup(program);
 upload.cliSetup(program);
 
 // Override global process.env type