Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

• deployments/docker-compose.yml
• README.md
• client/cmd/main.go
• api/util/api/api.go
• deployments/scripts/push-containers.sh
• client/analysis/output.go
• api/securitytest/securitytest.go

huskyCI is an open-source tool that orchestrates multiple static application security testing (SAST) tools and centralizes the results. It is designed to be integrated into CI/CD pipelines, acting as a dedicated stage to check for security flaws before deployment. When vulnerabilities are found, huskyCI provides detailed information including severity, confidence, file location, and the specific line of code.

This guide provides an overview of the huskyCI architecture and instructions for setting up a local development environment using Docker Compose. It covers the main components, configuration, and the basic workflow for initiating a security analysis.

Sources: README.md:10-13, README.md:17-21

Architecture Overview

The local huskyCI environment is composed of three main services orchestrated by Docker Compose. These services work together to receive analysis requests, run security scans, and store the results.

Sources: deployments/docker-compose.yml:2-8

The diagram below illustrates the high-level architecture and interactions between the core components.

Core Components

Service	Description
api	The main backend service. It exposes an API to start and monitor security analyses. It communicates with the dockerapi service to run security tools in isolated Docker containers and uses mongodb for data persistence.
mongodb	A MongoDB database instance used to store analysis results, security test configurations, and user data. The api service depends on this service being healthy before starting.
dockerapi	A Docker-in-Docker (dind) container that exposes the Docker Engine API over a TCP socket. This allows the api service to create and manage other Docker containers for running the various security scans.

Sources: deployments/docker-compose.yml:5-82

Local Environment Setup

You can run a full local instance of huskyCI using Docker Compose. This is the recommended method for development and testing.

Sources: README.md:43-44

Prerequisites

• Docker
• Docker Compose

Running the Stack

The entire application stack is defined in the docker-compose.yml file. To start all services, navigate to the deployments directory and run:

docker-compose up

This command will build the api image and start the api, mongodb, and dockerapi services.

Sources: deployments/docker-compose.yml

The following YAML snippet from docker-compose.yml shows the service definitions.

version: '3.8'
services:

    dockerapi:
        privileged: true
        image: docker:24-rc-dind
        container_name: huskyCI_Docker_API
        command: "dockerd --host=unix:///var/run/docker.sock --host=tcp://0.0.0.0:2376"
        # ...

    api:
        container_name: huskyCI_API
        environment:
            # ... (see configuration section)
        build:
            context: ../
            dockerfile: deployments/dockerfiles/api.Dockerfile
        command: ./huskyci-api-bin
        # ...
        depends_on:
            mongodb:
                condition: service_healthy
            dockerapi:
                condition: service_started

    mongodb:
        container_name: huskyCI_MongoDB
        image: mongo:4.2.2
        environment:
            MONGO_INITDB_ROOT_USERNAME: huskyCIUser
            MONGO_INITDB_ROOT_PASSWORD: huskyCIPassword
            MONGO_INITDB_DATABASE: huskyCIDB
        # ...

Sources: deployments/docker-compose.yml:1-70

Configuration

The api service is configured using environment variables. When running with Docker Compose, these can be set in the deployments/docker-compose.yml file.

Sources: deployments/docker-compose.yml:21-33, api/util/api/api.go:73-114

API Environment Variables

Variable	Description	Default Value (from docker-compose.yml)
HUSKYCI_DATABASE_DB_ADDR	Address of the MongoDB service.	mongodb
HUSKYCI_DATABASE_DB_NAME	Name of the database to use.	huskyCIDB
HUSKYCI_DATABASE_DB_USERNAME	Username for MongoDB authentication.	huskyCIUser
HUSKYCI_DATABASE_DB_PASSWORD	Password for MongoDB authentication.	huskyCIPassword
HUSKYCI_API_DEFAULT_USERNAME	Default username for the huskyCI API.	huskyCIUser
HUSKYCI_API_DEFAULT_PASSWORD	Default password for the huskyCI API.	huskyCIPassword
HUSKYCI_API_ALLOW_ORIGIN_CORS	CORS policy for the API.	*
HUSKYCI_DOCKERAPI_ADDR	Address of the Docker API service.	dockerapi
HUSKYCI_DOCKERAPI_TLS_VERIFY	Whether to verify TLS certificate of Docker API.	0
HUSKYCI_DOCKERAPI_CERT_PATH	Path inside the container to find Docker API certs.	/go/src/github.com/globocom/huskyCI/
HUSKYCI_INFRASTRUCTURE_USE	The container infrastructure to use.	docker

Sources: deployments/docker-compose.yml:23-33, api/util/api/api.go:73-90

Supported Security Tools

huskyCI supports a variety of SAST tools for different languages. Each tool runs in its own Docker container.

Language	Tool	Docker Image
Python	Bandit	huskyci/bandit
Python	Safety	huskyci/safety
Ruby	Brakeman	huskyci/brakeman
JavaScript	Npm Audit	huskyci/npmaudit
JavaScript	Yarn Audit	huskyci/yarnaudit
Go	Gosec	huskyci/gosec
Java	SpotBugs	huskyci/spotbugs
HCL	TFSec	huskyci/tfsec
Generic	GitLeaks	huskyci/gitleaks
C#	SecurityCodeScan	huskyci/securitycodescan

Sources: README.md:13-14, deployments/scripts/push-containers.sh:10-21, api/securitytest/securitytest.go:19-31

Client Workflow

The huskyci-client is a command-line tool used to interact with the huskyCI API. It handles starting an analysis, monitoring its progress, and displaying the final results.

The following diagram shows the sequence of operations performed by the client.

Analysis Output

Once an analysis is complete, the client prints the results to standard output. The output details each vulnerability found and concludes with a summary of findings per security tool.

Below is an example of the output format:

[HUSKYCI][*] poc-python-bandit -> https://github.com/globocom/huskyCI.git
[HUSKYCI][*] huskyCI analysis started! yDS9tb9mdt4QnnyvOBp3eVAXE1nWpTRQ

[HUSKYCI][!] Title: Use of exec detected.
[HUSKYCI][!] Language: Python
[HUSKYCI][!] Tool: Bandit
[HUSKYCI][!] Severity: MEDIUM
[HUSKYCI][!] Confidence: HIGH
[HUSKYCI][!] Details: Use of exec detected.
[HUSKYCI][!] File: ./main.py
[HUSKYCI][!] Line: 7
[HUSKYCI][!] Code:
6
7 exec(command)
8

[HUSKYCI][SUMMARY] Python -> huskyci/bandit:1.6.2
[HUSKYCI][SUMMARY] High: 0
[HUSKYCI][SUMMARY] Medium: 1
[HUSKYCI][SUMMARY] Low: 1
[HUSKYCI][SUMMARY] NoSecHusky: 1

[HUSKYCI][SUMMARY] Total
[HUSKYCI][SUMMARY] High: 0
[HUSKYCI][SUMMARY] Medium: 1
[HUSKYCI][SUMMARY] Low: 1
[HUSKYCI][SUMMARY] NoSecHusky: 1

[HUSKYCI][*] Some HIGH/MEDIUM issues were found in these securityTests:
[HUSKYCI][*] [huskyci/bandit:1.6.2]
ERROR: Job failed: exit code 190

Sources: README.md:23-64, client/analysis/output.go:429-440

If the JSON argument is provided to the client, the output will be in JSON format, containing a structured representation of all vulnerabilities and summaries.

Sources: client/cmd/main.go:19-21, client/analysis/output.go:12-19