@swimlane/swimlane-sdk

Swimlane Integrations CLI (SDK)

• Requirements
• Installation
• Usage
• Commands
• Roles and Works
• Release Flow

Requirements

• Docker Desktop
• nvm - (https://github.com/nvm-sh/nvm#installing-and-updating)
• Node >= 16.0.0
• Python >= 3.7

Installation

npm install -g @swimlane/swimlane-sdk@latest

Usage

$ npm install -g @swimlane/swimlane-sdk
$ swsdk COMMAND
running command...
$ swsdk (--version|-v)
@swimlane/swimlane-sdk/5.6.0 darwin-arm64 node-v16.20.2
$ swsdk --help [COMMAND]
USAGE
  $ swsdk COMMAND
...

Commands

• swsdk auth apphub login
• swsdk auth apphub logout
• swsdk auth bitwarden login
• swsdk auth bitwarden logout
• swsdk auth codacy login
• swsdk auth codacy logout
• swsdk auth github login
• swsdk auth github logout
• swsdk auth github show
• swsdk autocomplete [SHELL]
• swsdk commands
• swsdk config set
• swsdk config show
• swsdk help [COMMAND]
• swsdk hooks commit create
• swsdk integration build
• swsdk integration create-pr
• swsdk integration lint
• swsdk integration pre-commit
• swsdk integration scaffold
• swsdk integration test
• swsdk integration update
• swsdk integration validate
• swsdk integrations
• swsdk integrations get-all
• swsdk integrations list
• swsdk plugins
• swsdk plugins:install PLUGIN...
• swsdk plugins:inspect PLUGIN...
• swsdk plugins:install PLUGIN...
• swsdk plugins:link PLUGIN
• swsdk plugins:uninstall PLUGIN...
• swsdk plugins:uninstall PLUGIN...
• swsdk plugins:uninstall PLUGIN...
• swsdk plugins update
• swsdk task generate-inputs
• swsdk task generate-outputs
• swsdk task run
• swsdk task scaffold-task
• swsdk version
• swsdk which

swsdk auth apphub login

Use to login to AppHub

USAGE
  $ swsdk auth apphub login [-u <value>] [-p <value>] [-h]

FLAGS
  -h, --help              Show CLI help.
  -p, --password=<value>  AppHub password
  -u, --username=<value>  AppHub username

DESCRIPTION
  Use to login to AppHub

swsdk auth apphub logout

Use to logout to AppHub

USAGE
  $ swsdk auth apphub logout [-h]

FLAGS
  -h, --help  Show CLI help.

DESCRIPTION
  Use to logout to AppHub

swsdk auth bitwarden login

Use to login to Bitwarden

USAGE
  $ swsdk auth bitwarden login [-u <value>] [-p <value>] [-h]

FLAGS
  -h, --help              Show CLI help.
  -p, --password=<value>  Bitwarden password
  -u, --username=<value>  Bitwarden username

DESCRIPTION
  Use to login to Bitwarden

swsdk auth bitwarden logout

Use to login to Bitwarden

USAGE
  $ swsdk auth bitwarden logout [-h]

FLAGS
  -h, --help  Show CLI help.

DESCRIPTION
  Use to login to Bitwarden

swsdk auth codacy login

Use to store API Key to codacy

USAGE
  $ swsdk auth codacy login -k <value> [-h]

FLAGS
  -h, --help             Show CLI help.
  -k, --api-key=<value>  (required) codacy api key

DESCRIPTION
  Use to store API Key to codacy

swsdk auth codacy logout

Use to logout of codacy

USAGE
  $ swsdk auth codacy logout [-h]

FLAGS
  -h, --help  Show CLI help.

DESCRIPTION
  Use to logout of codacy

swsdk auth github login

Use to login to Github

USAGE
  $ swsdk auth github login [-c <value>] [-o <value>] [-h]

FLAGS
  -c, --clientId=<value>  [default: 0d418a5615c458b0b593] client id of the authentication app
  -h, --help              Show CLI help.
  -o, --org=<value>       [default: swimlane] the organization name

DESCRIPTION
  Use to login to Github

swsdk auth github logout

Use to logout to Github

USAGE
  $ swsdk auth github logout [-c <value>] [-o <value>] [-h]

FLAGS
  -c, --clientId=<value>  [default: 0d418a5615c458b0b593] client id of the authentication app
  -h, --help              Show CLI help.
  -o, --org=<value>       [default: swimlane] the organization name

DESCRIPTION
  Use to logout to Github

swsdk auth github show

Use to login to Github

USAGE
  $ swsdk auth github show [-c <value>] [-o <value>] [-h]

FLAGS
  -c, --clientId=<value>  [default: 0d418a5615c458b0b593] client id of the authentication app
  -h, --help              Show CLI help.
  -o, --org=<value>       [default: swimlane] the organization name

DESCRIPTION
  Use to login to Github

swsdk autocomplete [SHELL]

display autocomplete installation instructions

USAGE
  $ swsdk autocomplete [SHELL] [-r]

ARGUMENTS
  SHELL  shell type

FLAGS
  -r, --refresh-cache  Refresh cache (ignores displaying instructions)

DESCRIPTION
  display autocomplete installation instructions

EXAMPLES
  $ swsdk autocomplete

  $ swsdk autocomplete bash

  $ swsdk autocomplete zsh

  $ swsdk autocomplete --refresh-cache

See code: @oclif/plugin-autocomplete

swsdk commands

list all the commands

USAGE
  $ swsdk commands [--json] [-h] [--hidden] [--columns <value> | -x] [--sort <value>] [--filter <value>]
    [--output csv|json|yaml |  | [--csv | --no-truncate]] [--no-header | ]

FLAGS
  -h, --help         Show CLI help.
  -x, --extended     show extra columns
  --columns=<value>  only show provided columns (comma-separated)
  --csv              output is csv format [alias: --output=csv]
  --filter=<value>   filter property by partial string matching, ex: name=foo
  --hidden           show hidden commands
  --no-header        hide table header from output
  --no-truncate      do not truncate output to fit screen
  --output=<option>  output in a more machine friendly format
                     <options: csv|json|yaml>
  --sort=<value>     property to sort by (prepend '-' for descending)

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  list all the commands

See code: @oclif/plugin-commands

swsdk config set

Use to set config options

USAGE
  $ swsdk config set [--git-protocol https|ssh] [--owner <value>] [-h]

FLAGS
  -h, --help               Show CLI help.
  --git-protocol=<option>  the protocol to use for git clone and push operations
                           <options: https|ssh>
  --owner=<value>          the default GitHub Owner

DESCRIPTION
  Use to set config options

swsdk config show

Used display current config settings

USAGE
  $ swsdk config show [-h]

FLAGS
  -h, --help  Show CLI help.

DESCRIPTION
  Used display current config settings

swsdk help [COMMAND]

Display help for swsdk.

USAGE
  $ swsdk help [COMMAND] [-n]

ARGUMENTS
  COMMAND  Command to show help for.

FLAGS
  -n, --nested-commands  Include all nested commands in the output.

DESCRIPTION
  Display help for swsdk.

See code: @oclif/plugin-help

swsdk hooks commit create

Installs and sets up commitizen

USAGE
  $ swsdk hooks commit create [--global] [--skip-hook] [-h]

FLAGS
  -h, --help   Show CLI help.
  --global     used to configure the hook globally
  --skip-hook  skips setting up the prepare-commit hook. Must be run with cz or git cz

DESCRIPTION
  Installs and sets up commitizen

swsdk integration build

Use to build an integration (.swimbundle)

USAGE
  $ swsdk integration build [-h] [-i <value> | -v 3.6|3.7|3.12] [-d <value>] [-s]

FLAGS
  -d, --directory=<value>        [default: ./] current directory to mount
  -h, --help                     Show CLI help.
  -i, --image=<value>            image to use
  -s, --skip-pull                skips pulling the image
  -v, --python-version=<option>  [default: 3.6] python version to use
                                 <options: 3.6|3.7|3.12>

DESCRIPTION
  Use to build an integration (.swimbundle)

swsdk integration create-pr

Use to create a PR for an integration

USAGE
  $ swsdk integration create-pr -t <value> [-h] [-d <value>] [-b <value>] [-d <value>] [-o <value>] [--draft] [-n <value>]
    [-r <value>]

FLAGS
  -b, --branch=<value>        The name branch
  -d, --description=<value>   description of the pull request
  -d, --directory=<value>     [default: ./] current directory to mount
  -h, --help                  Show CLI help.
  -n, --name=<value>          GitHub repository
  -o, --organization=<value>  [default: swimlane] GitHub organization
  -r, --reviewer=<value>...   [default: swimlane/surf] GitHub user for the PR review
  -t, --title=<value>         (required) name of the pull request
  --draft                     create the PR as a draft

DESCRIPTION
  Use to create a PR for an integration

swsdk integration lint

Use to validate source code through static analysis

USAGE
  $ swsdk integration lint -t <value> [-h] [-i <value>] [-s] [-v] [-d <value>]

FLAGS
  -d, --directory=<value>  [default: ./] current directory to mount
  -h, --help               Show CLI help.
  -i, --image=<value>      [default: docker.io/codacy/codacy-analysis-cli] image to use
  -s, --skip-pull          skips pulling the image
  -t, --tool=<value>...    (required) [default: bandit,jackson-linter,prospector,pylint-python3,remark-lint] plugins
                           used in analysis (https://docs.codacy.com/repositories-configure/codacy-configuration-file/#w
                           hich-tools-can-be-configured-and-which-name-should-i-use)
  -v, --verbose            verbose logging

DESCRIPTION
  Use to validate source code through static analysis

swsdk integration pre-commit

Use to install a pre-commit hook on an integration, if the hook is already installed will be updated.

USAGE
  $ swsdk integration pre-commit [-h]

FLAGS
  -h, --help  Show CLI help.

DESCRIPTION
  Use to install a pre-commit hook on an integration, if the hook is already installed will be updated.

swsdk integration scaffold

Use to scaffold a new integration

USAGE
  $ swsdk integration scaffold [-d <value>] [-i <value>] [-h] [--vendor <value>] [--product <value>] [--family
    Investigation|Endpoint Security & Management|Network Security & Management|Communication|SIEM & Log
    Management|Governance & Risk Management|Vulnerability & Patch Management|Ticket Management|DevOps & Application
    Security|Identity & Access Management|Infrastructure|Miscellaneous] [--description <value>] [--logoPath <value>]
    [--requirements <value>] [--use-rest-template] [--generate-examples] [--supported-swimlane-version <value>]
    [--author <value>] [--author-email <value>] [--url <value>]

FLAGS
  -d, --directory=<value>               [default: ./] directory to scaffold
  -h, --help                            Show CLI help.
  -i, --input-config=<value>            input config file
  --author=<value>                      Integration Author
  --author-email=<value>                Integration Author Email
  --description=<value>                 Description (e.g. CrowdStrike Host Query API)
  --family=<option>                     Integration Family
                                        <options: Investigation|Endpoint Security & Management|Network Security &
                                        Management|Communication|SIEM & Log Management|Governance & Risk
                                        Management|Vulnerability & Patch Management|Ticket Management|DevOps &
                                        Application Security|Identity & Access Management|Infrastructure|Miscellaneous>
  --generate-examples                   Generate example code
  --logoPath=<value>                    URL or absolute path to logo file
  --product=<value>                     Product (e.g. Falcon)
  --requirements=<value>                Requirements, comma separated (e.g. basic-rest-endpoint,pyflattener)
  --supported-swimlane-version=<value>  What is the supported Swimlane Version (>=10.3.0)
  --url=<value>                         Author URL
  --use-rest-template                   Use the basic rest template
  --vendor=<value>                      Vendor (e.g. CrowdStrike)

DESCRIPTION
  Use to scaffold a new integration

swsdk integration test

Use to test an integration (.swimbundle)

USAGE
  $ swsdk integration test [-h] [-i <value> | -v 3.6|3.7|3.12] [-d <value>] [-s] [-f] [--report-portal-uuid <value> -r
    --report-portal-host <value> --report-portal-project <value>] [--report-portal-launch <value>   ]

FLAGS
  -d, --directory=<value>          [default: ./] current directory to mount
  -f, --force-rebuild              forces nocache on the image build
  -h, --help                       Show CLI help.
  -i, --image=<value>              image to use
  -r, --report-portal              Send results to report portal
  -s, --skip-pull                  skips pulling the image
  -v, --python-version=<option>    [default: 3.6] python version to use
                                   <options: 3.6|3.7|3.12>
  --report-portal-host=<value>     Report Portal host.
  --report-portal-launch=<value>   Report Portal launch.
  --report-portal-project=<value>  Report Portal project.
  --report-portal-uuid=<value>     Report Portal UUID.

DESCRIPTION
  Use to test an integration (.swimbundle)

swsdk integration update

Use to update the version or image of an integration

USAGE
  $ swsdk integration update [-h] [-d <value>] [--logo-path <value>] [-v <value> | -t major|minor|patch |
    --conventional-commits] [--preid <value> ] [--skip-commit ] [--dry-run] [--scaffold-pytest]

FLAGS
  -d, --directory=<value>  [default: ./] Current directory to mount
  -h, --help               Show CLI help.
  -t, --type=<option>      [default: patch] Increments based on the type
                           <options: major|minor|patch>
  -v, --version=<value>    Sets the current version
  --conventional-commits   Use conventional-changelog to determine version bump and generate CHANGELOG.
  --dry-run                Does not write the new version
  --logo-path=<value>      URL or absolute path to logo file
  --preid=<value>          [default: alpha] Specify the prerelease identifier when versioning a prerelease
  --scaffold-pytest        Create the directory structure for pytest.
  --skip-commit            If using conventional commits, this flag will skip committing the change

DESCRIPTION
  Use to update the version or image of an integration

swsdk integration validate

Use to validate an integration

USAGE
  $ swsdk integration validate [-h] [-i <value> | -v 3.6|3.7|3.12] [-s] [-d <value>]

FLAGS
  -d, --directory=<value>        [default: ./] current directory to mount
  -h, --help                     Show CLI help.
  -i, --image=<value>            image to use
  -s, --skip-pull                skips pulling the image
  -v, --python-version=<option>  [default: 3.6] python version to use
                                 <options: 3.6|3.7|3.12>

DESCRIPTION
  Use to validate an integration

swsdk integrations

Use to get (clone) an integration

USAGE
  $ swsdk integrations [-n <value>] [-d <value>] [-h] [-p]

FLAGS
  -d, --directory=<value>  [default: ./] root directory to clone the repo
  -h, --help               Show CLI help.
  -n, --name=<value>       name of the new integration (repo name and final directory name)
  -p, --pre-commit         Use to install the pre-commit hook

DESCRIPTION
  Use to get (clone) an integration

See code: @swsdk/plugin-integrations

swsdk integrations get-all

Use to get (clone) all the integrations

USAGE
  $ swsdk integrations get-all [-d <value>] [-h] [--concurrency <value>] [--continue-on-error true|false]

FLAGS
  -d, --directory=<value>       [default: ./] root directory to clone the repo
  -h, --help                    Show CLI help.
  --concurrency=<value>         [default: 6] number of max jobs
  --continue-on-error=<option>  [default: true] continue even if there is an error
                                <options: true|false>

DESCRIPTION
  Use to get (clone) all the integrations

swsdk integrations list

Use to list all the integrations you have access to on GitHub

USAGE
  $ swsdk integrations list [-h]

FLAGS
  -h, --help  Show CLI help.

DESCRIPTION
  Use to list all the integrations you have access to on GitHub

swsdk plugins

List installed plugins.

USAGE
  $ swsdk plugins [--core]

FLAGS
  --core  Show core plugins.

DESCRIPTION
  List installed plugins.

EXAMPLES
  $ swsdk plugins

See code: @oclif/plugin-plugins

swsdk plugins:install PLUGIN...

Installs a plugin into the CLI.

USAGE
  $ swsdk plugins:install PLUGIN...

ARGUMENTS
  PLUGIN  Plugin to install.

FLAGS
  -f, --force    Run yarn install with force flag.
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Installs a plugin into the CLI.

  Can be installed from npm or a git url.

  Installation of a user-installed plugin will override a core plugin.

  e.g. If you have a core plugin that has a 'hello' command, installing a user-installed plugin with a 'hello' command
  will override the core plugin implementation. This is useful if a user needs to update core plugin functionality in
  the CLI without the need to patch and update the whole CLI.

ALIASES
  $ swsdk plugins add

EXAMPLES
  $ swsdk plugins:install myplugin 

  $ swsdk plugins:install https://github.com/someuser/someplugin

  $ swsdk plugins:install someuser/someplugin

swsdk plugins:inspect PLUGIN...

Displays installation properties of a plugin.

USAGE
  $ swsdk plugins:inspect PLUGIN...

ARGUMENTS
  PLUGIN  [default: .] Plugin to inspect.

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Displays installation properties of a plugin.

EXAMPLES
  $ swsdk plugins:inspect myplugin

swsdk plugins:install PLUGIN...

Installs a plugin into the CLI.

USAGE
  $ swsdk plugins:install PLUGIN...

ARGUMENTS
  PLUGIN  Plugin to install.

FLAGS
  -f, --force    Run yarn install with force flag.
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Installs a plugin into the CLI.

  Can be installed from npm or a git url.

  Installation of a user-installed plugin will override a core plugin.

  e.g. If you have a core plugin that has a 'hello' command, installing a user-installed plugin with a 'hello' command
  will override the core plugin implementation. This is useful if a user needs to update core plugin functionality in
  the CLI without the need to patch and update the whole CLI.

ALIASES
  $ swsdk plugins add

EXAMPLES
  $ swsdk plugins:install myplugin 

  $ swsdk plugins:install https://github.com/someuser/someplugin

  $ swsdk plugins:install someuser/someplugin

swsdk plugins:link PLUGIN

Links a plugin into the CLI for development.

USAGE
  $ swsdk plugins:link PLUGIN

ARGUMENTS
  PATH  [default: .] path to plugin

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Links a plugin into the CLI for development.

  Installation of a linked plugin will override a user-installed or core plugin.

  e.g. If you have a user-installed or core plugin that has a 'hello' command, installing a linked plugin with a 'hello'
  command will override the user-installed or core plugin implementation. This is useful for development work.

EXAMPLES
  $ swsdk plugins:link myplugin

swsdk plugins:uninstall PLUGIN...

Removes a plugin from the CLI.

USAGE
  $ swsdk plugins:uninstall PLUGIN...

ARGUMENTS
  PLUGIN  plugin to uninstall

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Removes a plugin from the CLI.

ALIASES
  $ swsdk plugins unlink
  $ swsdk plugins remove

swsdk plugins:uninstall PLUGIN...

Removes a plugin from the CLI.

USAGE
  $ swsdk plugins:uninstall PLUGIN...

ARGUMENTS
  PLUGIN  plugin to uninstall

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Removes a plugin from the CLI.

ALIASES
  $ swsdk plugins unlink
  $ swsdk plugins remove

swsdk plugins:uninstall PLUGIN...

Removes a plugin from the CLI.

USAGE
  $ swsdk plugins:uninstall PLUGIN...

ARGUMENTS
  PLUGIN  plugin to uninstall

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Removes a plugin from the CLI.

ALIASES
  $ swsdk plugins unlink
  $ swsdk plugins remove

swsdk plugins update

Update installed plugins.

USAGE
  $ swsdk plugins update [-h] [-v]

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Update installed plugins.

swsdk task generate-inputs

Generate task manifest inputs from test data.

USAGE
  $ swsdk task generate-inputs [-n <value>] [-d <value>] [--inputs <value>] [-a] [-p] [-h]

FLAGS
  -a, --append             append new inputs to existing.
  -d, --directory=<value>  [default: ./] root directory of the repository.
  -h, --help               Show CLI help.
  -n, --name=<value>       task name to generate inputs.
  -p, --interactive        prompts to add description and required for each input.
  --inputs=<value>         input data as JSON

DESCRIPTION
  Generate task manifest inputs from test data.

swsdk task generate-outputs

Generate a task manifest outputs from test data.

USAGE
  $ swsdk task generate-outputs [-n <value>] [-d <value>] [--outputs <value>] [-a] [-h]

FLAGS
  -a, --append             append new outputs to existing.
  -d, --directory=<value>  [default: ./] root directory of the repository.
  -h, --help               Show CLI help.
  -n, --name=<value>       task name to generate outputs.
  --outputs=<value>        Filename to write JSON outputs, defaults to the task "name". ie: data/name_outputs.json

DESCRIPTION
  Generate a task manifest outputs from test data.

swsdk task run

Use to test a task in an integration

USAGE
  $ swsdk task run --asset <value> [-h] [-i <value> | -v 3.6|3.7|3.12] [-n <value>] [-d <value>] [-g]
    [--inputs <value>] [-t <value>] [-s] [-f] [-d code] [--pycharm-host <value>] [--pycharm-port <value>]

FLAGS
  -d, --debug=<option>           enable debugging
                                 <options: code>
  -d, --directory=<value>        [default: ./] current directory to mount
  -f, --force-rebuild            forces nocache on the image build
  -g, --generate                 generates the asset and input files in the current directory
  -h, --help                     Show CLI help.
  -i, --image=<value>            image to use
  -n, --name=<value>             task name to run
  -s, --skip-pull                skips pulling the image
  -t, --generate-test=<value>    Generate a test case using this run. Provide the name of the test
  -v, --python-version=<option>  [default: 3.6] python version to use
                                 <options: 3.6|3.7|3.12>
  --asset=<value>                (required) [default: data/asset.json] asset json
  --inputs=<value>               Filename for JSON inputs, defaults to the task name under the data folder. ie:
                                 data/my_task.json
  --pycharm-host=<value>         [default: host.docker.internal] pycharm debugging host
  --pycharm-port=<value>         [default: 30000] pycharm debugging port

DESCRIPTION
  Use to test a task in an integration

swsdk task scaffold-task

Use to scaffold a new task in an integration.

USAGE
  $ swsdk task scaffold-task [-d <value>] [-h] [-n <value>] [--copy-task <value> | --new] [--description <value>]

FLAGS
  -d, --directory=<value>  [default: ./] directory to scaffold
  -h, --help               Show CLI help.
  -n, --name=<value>       task name
  --copy-task=<value>      name of the task to copy
  --description=<value>    description (e.g. CrowdStrike Host Query API)
  --new                    generates a new task

DESCRIPTION
  Use to scaffold a new task in an integration.

swsdk version

USAGE
  $ swsdk version

See code: @oclif/plugin-version

swsdk which

Show which plugin a command is in.

USAGE
  $ swsdk which

DESCRIPTION
  Show which plugin a command is in.

See code: @oclif/plugin-which

Roles and Works

1. [Person] Develop and Submit Release Pull Request
2. [Team] Review Release Pull Request
3. [CI] Publish

Release Flow

0. [Local] Checkout release branch: git checkout release/<uniq>
1. [Local] Run yarn run versionup
   • Update CHANGELOG.md and package.json's version, and lerna.json's version
   • It does not git tag
2. [Local] Submit to Release Pull Request
3. [GitHub] Review Release Pull Request
4. [GitHub] Write Release Note into the Release Pull Request's body
5. [GitHub] Merge Release Pull Request
6. [CI] Create git tag && Create GitHub Release && publish to npm(GitHub Package Registry)
   • 📝 The GitHub Release's body is copied from Release Pull Request's body

Quickstart

See Quickstart

Contributing

See Contributing

Testing

See Integration Tests