Home
Relevant source files
The following files were used as context for generating this wiki page:huskyCI is an open-source tool designed to orchestrate various static application security testing (SAST) tools and centralize their results. It integrates into CI/CD pipelines, allowing developers to identify security flaws before deployment. The system performs security analysis for multiple languages, audits for secrets, and consolidates all findings into a single database for metrics and review.
The core functionality revolves around a client-server architecture. A developer triggers an analysis via the huskyCI client within their CI pipeline. The huskyCI API server then orchestrates the execution of multiple security tools in isolated Docker containers or Kubernetes pods, analyzes the outputs, and reports the consolidated results.
Sources: README.md, client/cmd/main.go, api/securitytest/securitytest.go
How It Works
Developers integrate huskyCI by adding a new stage to their CI pipeline. This stage executes the huskyCI client, which communicates with the huskyCI API to initiate a security scan on the specified repository and branch.
If the analysis finds vulnerabilities, huskyCI provides detailed information, including severity, confidence, file path, line number, and the vulnerable code snippet. The CI job can be configured to fail if high or medium severity vulnerabilities are detected, thus blocking insecure code from proceeding in the pipeline.
Sources: README.md, client/cmd/main.go:121-131
The following diagram illustrates the high-level interaction between the developer's CI pipeline and huskyCI.
Sources: README.md, client/cmd/main.go
Architecture
huskyCI is composed of several services that run in containers, as defined in the docker-compose.yml file. The primary components are the API server, a MongoDB database, and a Docker-in-Docker (dind) instance for running the security tools.
This diagram shows the main services and their interactions within the huskyCI environment.
Sources: deployments/docker-compose.yml
Components
| Service | Image | Description |
|---|---|---|
| api | builds from deployments/dockerfiles/api.Dockerfile | The core backend service. It exposes an HTTP API to receive analysis requests, orchestrates security scans using the Docker API, parses results, and stores them in MongoDB. |
| dockerapi | docker:24-rc-dind | A Docker-in-Docker (dind) service that exposes the Docker API. The api service uses this to create and run the individual security tool containers for each analysis. |
| mongodb | mongo:4.2.2 | The database used to store security test definitions, analysis requests, and all vulnerability results. |
Sources: deployments/docker-compose.yml
Analysis Workflow
The analysis process is split between the client-side CLI and the server-side API.
Client-Side (CLI) Workflow
The huskyci-client binary orchestrates the analysis from the user's machine or CI environment.
This flowchart outlines the steps executed by the huskyCI client.
Sources: client/cmd/main.go
Server-Side (API) Workflow
When the API receives an analysis request, it runs each configured security test in a separate container or pod.
This flowchart shows the process the huskyCI API follows to execute a security test.
Sources: api/securitytest/securitytest.go
Supported Tools
huskyCI supports a variety of security tools for different languages and purposes. The client can automatically detect the languages in a project and run the corresponding tools.
| Language | Tool | Docker Image |
|---|---|---|
| Go | Gosec | huskyci/gosec |
| Python | Bandit | huskyci/bandit |
| Python | Safety | huskyci/safety |
| Ruby | Brakeman | huskyci/brakeman |
| JavaScript | Npm Audit | huskyci/npmaudit |
| JavaScript | Yarn Audit | huskyci/yarnaudit |
| Java | SpotBugs | huskyci/spotbugs |
| HCL | TFSec | huskyci/tfsec |
| C# | Security Code Scan | huskyci/securitycodescan |
| Generic | GitLeaks | huskyci/gitleaks |
Sources: README.md, cli/analysis/analysis.go:142-167
Output and Reporting
huskyCI provides results in multiple formats for different use cases.
Standard Output (STDOUT)
By default, results are printed to the standard output in a human-readable format. This includes a detailed view of each vulnerability and a final summary.
Example Vulnerability Output:
[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
Sources: README.md, client/analysis/output.go:445-460
Example Summary Output:
[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
Sources: README.md, client/analysis/output.go:312-386
SonarQube Integration
huskyCI can generate a sonarqube.json report file, which can be imported into SonarQube. This integration maps huskyCI's vulnerability data to the SonarQube generic issue format.
The severity levels are mapped as follows:
| huskyCI Severity | SonarQube Severity |
|---|---|
high | BLOCKER |
medium | MAJOR |
low | MINOR |
| other | INFO |
For vulnerabilities not associated with a specific file (e.g., dependency issues), a placeholder file named huskyCI_Placeholder_File is created and referenced in the report.
Sources: client/integration/sonarqube/sonarqube.go:70-82, client/integration/sonarqube/sonarqube.go:19-26, client/cmd/main.go:78-82
Core Data Structures
The huskyCI client relies on several key data structures to manage analysis data. These are defined in cli/types/types.go.
The following diagram shows the relationship between the main analysis structures.
Sources: cli/types/types.go