The Connector Toolkit

April 29, 2024 15:04

Note: For more information and detailed instructions on the Connector Toolkit, see GitHub.

The Toolkit is a set of functions for data and API scripts you can use with Cisco Vulnerability Management. It's organized into tasks which are units of functionality that can be called and used from the command line.

Note: To use it quickly with tools like Docker or Podman, use Containerfile (Dockerfile).

For more information about the specific connectors in the Toolkit, see the following list:

Important: This software is provided "as is" without warranty of any kind, express or implied; including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.

System Requirements

A container tool capable of running a standalone docker image.
- Podman
- Docker
8GB RAM
Network Access

Running the Latest Image

To get started easily, use the pre-built image on Docker Hub.

Example 1

The following example pulls the latest image, and prints the list of tasks:

docker pull kennasecurity/toolkit && docker run -it kennasecurity/toolkit

Example 2

The following (a little more complicated) example uses an extra line that pulls the latest image and executes a task to check your API key:

docker pull kennasecurity/toolkit && docker run -it kennasecurity/toolkit task=kenna_api_key_check kenna_api_key=$KENNA_API_KEY

Running on GitHub Actions

To run the Toolkit on GitHub Actions, use your CI/CD available minutes.

For more information, see the following detailed instructions.

Building Your Own Image

If you've made some modifications to the code or just want to build the image yourself, it's easy to do. To build the image, use one the following commands:

To Build Your Own Image with Docker use:

docker build . -t toolkit:latest

To Build Your Own Image with Podman use:

podman build . -t toolkit:latest

Launching Your Own Container Image

Excellent, now that you have an image, you are ready to launch it!

To Launch Your Own Container Image Docker use:

docker run -it --rm toolkit:latest

To Launch Your Own Container Image Podman use:

podman run -it --rm toolkit:latest

If everything's working well, use tasks to access the toolkit's functionality.

Calling a Specific Task

To utilize the toolkit's functionality, pass a 'task=[name of task]' argument. Use TODO as a task name and one of the following tasks:

To Call a Specific Task with Docker:

docker run -it --rm toolkit:latest task=example

To call a Specific Task with Podman:

podman run -it --rm toolkit:latest task=example

Calling a Task with Arguments

Sometimes, you need to send arguments to tasks to specify how they should behave.

Each task has its own arguments, and the toolkit attempts to make it simple to pass additional arguments. The format for passing variables is in key=value, separated by spaces. See the following example:

'arg1=val1 arg2=val2 arg3=val3'

To get task line help and to use the available readme.md files, use the following command:

docker run -it --rm -t toolkit:latest task=csv2kdi:help #(task's parameter help) docker run -it --rm -t toolkit:latest task=csv2kdi:readme #(task's readme in a paging format)

The following commands are 'aws_inspector' task examples with arguments included:

For Docker:

docker run -it --rm -t toolkit:latest task=aws_inspector aws_region=us-east-1 aws_access_key=$AWS_ACCESS_KEY aws_secret_key='$AWS_SECRET_KEY'

For Podman:

podman run -it --rm -t toolkit:latest task=aws_inspector aws_region=us-east-1 aws_access_key=$AWS_ACCESS_KEY aws_secret_key='$AWS_SECRET_KEY'

Getting Data In and Out of the API

Many tasks require input and output JSON or log files. To handle these files, use Docker volumes that are mapped into the container's operating system at runtime. The toolkit's tasks are programmed to use directories relative to "/opt/toolkit" to facilitate the input and output process. Specifically, tasks use the following directories as the base when searching for files:

- Default Input Directory: /opt/toolkit/input
- Default Output Directory: /opt/toolkit/output

Configuring Persistent Storage Volumes

Use the following examples to map volumes to directories on your local system, for both input and output.

To Configure a Volume with Docker:

docker run  -it --rm \
-v ~/Desktop/toolkit_input:/opt/app/toolkit/input \
-v ~/Desktop/toolkit_output:/opt/app/toolkit/output \
-t toolkit:latest task=example

To Configure a Volume with Podman:

podman run  -it --rm \
-v ~/Desktop/toolkit_input:/opt/app/toolkit/input \
-v ~/Desktop/toolkit_output:/opt/app/toolkit/output \
-t toolkit:latest task=example

Toolkit Capabilities (TASKS)

To see the current tasks that are available, see the Tasks Readme.md.

Advanced Usage with a Proxy

If you need to use a proxy with this container, the suggested implementation is to use the built-in Docker or Podman proxy support.

Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: www.cisco.com/go/trademarks. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1721R)