CLI Usage Guide

Relevant source files

The following files were used as context for generating this wiki page: - [cli/config/config.go](https://github.com/rafaveira3/huskyCI/blob/HEAD/cli/config/config.go) - [client/cmd/main.go](https://github.com/rafaveira3/huskyCI/blob/HEAD/client/cmd/main.go) - [cli/analysis/analysis.go](https://github.com/rafaveira3/huskyCI/blob/HEAD/cli/analysis/analysis.go) - [client/analysis/output.go](https://github.com/rafaveira3/huskyCI/blob/HEAD/client/analysis/output.go) - [README.md](https://github.com/rafaveira3/huskyCI/blob/HEAD/README.md) - [api/server.go](https://github.com/rafaveira3/huskyCI/blob/HEAD/api/server.go) - [api/util/util.go](https://github.com/rafaveira3/huskyCI/blob/HEAD/api/util/util.go) - [client/integration/sonarqube/sonarqube_test.go](https://github.com/rafaveira3/huskyCI/blob/HEAD/client/integration/sonarqube/sonarqube_test.go)

The huskyCI command-line interface (CLI) is the primary tool for developers to interact with the huskyCI analysis engine. It is designed to be integrated into CI/CD pipelines to perform static security analysis on code repositories. The CLI orchestrates security tests, retrieves the results, and provides immediate feedback, blocking the pipeline if critical vulnerabilities are found.

This guide provides a comprehensive overview of the CLI's configuration, workflow, and output formats, based on its source code. It is intended for developers and DevOps engineers who are setting up or using huskyCI for security testing.

Configuration

The CLI can be configured through environment variables or a local configuration file. The configuration file is located at $HOME/.huskyci/config.yaml.

Configuration Loading

The CLI first checks for specific environment variables. If they are present, it uses them to configure the API endpoint and authentication token. If not, it falls back to the config.yaml file to determine the current target.

The diagram below illustrates the configuration loading logic.

This flow is managed by the GetCurrentTarget function.
Sources: cli/config/config.go:13-50

Configuration Management

The CLI manages API connection settings through "targets". A target consists of a label, an API endpoint, and a token storage method. While the source files for targetAdd and targetList were not provided for this analysis, the configuration structure indicates their purpose.

Key configuration functions include:

• CheckAndCreateConfigFolder: Ensures the $HOME/.huskyci directory exists.
• CreateConfigFile: Creates the config.yaml file if it's missing.

Sources: cli/config/config.go:53-91

Analysis Workflow

The main function of the CLI is to initiate and monitor a security analysis. The process is executed by the main function in client/cmd/main.go.

The workflow consists of the following steps:

1. Configuration Check: Verifies that the necessary environment variables or configuration files are set.
2. Start Analysis: Sends a request to the huskyCI API to start a new analysis and receives a unique Request ID (RID).
3. Monitor Analysis: Polls the API using the RID until the analysis status is "finished".
4. Process and Print Results: Parses the results from the API and prints them to STDOUT or as a JSON object.
5. Generate SonarQube Report: Creates a sonarqube.json file for integration with SonarQube.
6. Set Exit Code: Exits with a specific status code (190) if blocking vulnerabilities (HIGH/MEDIUM severity) are found, or 0 otherwise.

Sources: client/cmd/main.go

High-Level Flow

The following diagram shows the sequence of operations performed by the CLI during an analysis run.

Client-Server Interaction

The CLI communicates with the huskyCI API server over HTTP/S. The key interactions are for starting and monitoring the analysis.

Output Formatting

The CLI provides two output formats: a human-readable STDOUT format and a machine-readable JSON format. The format is selected by passing JSON as the first argument to the client.

Sources: client/cmd/main.go:21-23

Standard Output (STDOUT)

The STDOUT format is designed for easy reading in a terminal. It lists each vulnerability with detailed information and concludes with a summary.

An example of the STDOUT 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

Sources: README.md:28-68, client/analysis/output.go:502-581

The fields displayed for each vulnerability depend on the security tool that found it. The table below details the common fields.

Field	Description	Source File
Title	A brief description of the vulnerability.	client/analysis/output.go
Language	The programming language of the affected code.	client/analysis/output.go
Tool	The security tool that reported the finding.	client/analysis/output.go
Severity	The severity level (e.g., HIGH, MEDIUM, LOW).	client/analysis/output.go
Confidence	The confidence level of the finding (e.g., HIGH, MEDIUM).	client/analysis/output.go
Details	A more detailed explanation of the issue.	client/analysis/output.go
File	The path to the affected file.	client/analysis/output.go
Line	The line number where the vulnerability occurs.	client/analysis/output.go
Code	A snippet of the vulnerable code.	client/analysis/output.go

JSON Output

When the JSON argument is used, the CLI outputs a single JSON object containing all analysis results. This is useful for programmatic processing. The structure of this output is defined by types.JSONOutput.

Sources: client/analysis/output.go:13-19

Supported Security Tools

The CLI can orchestrate a variety of security tools based on the languages detected in the target project. The mapping of languages to tools is defined internally.

Language	Security Tools
Go	huskyci/gosec
Python	huskyci/bandit, huskyci/safety
Ruby	huskyci/brakeman
JavaScript	huskyci/npmaudit, huskyci/yarnaudit
Java	huskyci/spotbugs
HCL	huskyci/tfsec
C#	huskyci/securitycodescan
Generic	huskyci/gitleaks

This list is generated by the getAvailableSecurityTests function.
Sources: cli/analysis/analysis.go:149-175

Integrations

SonarQube

After an analysis completes, the CLI automatically generates a sonarqube.json file in a ./huskyCI/ directory. This file is formatted for import into SonarQube, allowing huskyCI's findings to be viewed within the SonarQube dashboard.

Sources: client/cmd/main.go:82-86, client/integration/sonarqube/sonarqube_test.go:29-32

Conclusion

The huskyCI CLI is a powerful and flexible tool for integrating automated security testing into development workflows. By wrapping the complexity of various security scanners and the huskyCI API, it provides a simple, unified interface for developers. Its clear pass/fail mechanism, based on vulnerability severity, makes it an effective gatekeeper in CI/CD pipelines, helping to prevent security flaws from reaching production.