API Endpoints: Analysis

Relevant source files

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

• api/routes/analysis.go
• api/server.go
• client/analysis/analysis.go
• client/cmd/main.go
• cli/analysis/analysis.go
• api/securitytest/npmaudit.go
• api/securitytest/brakeman.go

The Analysis API endpoints are the core of huskyCI, providing the interface for clients to submit code repositories for security scanning and to retrieve the results. This system is designed to be asynchronous, where a client initiates an analysis and then polls for its completion.

The primary interactions involve two main REST endpoints: one to create a new analysis request and another to fetch the status and results of a specific analysis. The client-side tooling, such as the huskyci-client, is built around these endpoints to provide a seamless experience within a CI/CD pipeline.

Sources: api/server.go:51-52, client/cmd/main.go:34-51

API Endpoint Summary

The analysis functionality is exposed through two main routes.

Method	Path	Handler Function	Description
POST	/analysis	ReceiveRequest	Submits a new repository for analysis.
GET	/analysis/:id	GetAnalysis	Retrieves the status and results of an analysis by its Request ID (RID).

Sources: api/server.go:51-52

Starting a New Analysis (POST /analysis)

This endpoint initiates a new security analysis for a given repository. The request is handled by the ReceiveRequest function. The process is asynchronous; the API accepts the request, performs initial validation, and if successful, starts the analysis in a background goroutine.

Sources: api/routes/analysis.go:85-151

Request

• Header: Husky-Token (string, required) - An authorization token.
• Body: A JSON object representing the repository to be analyzed.

The request body should conform to the types.Repository structure, as shown by its usage in the client.

Field	Type	Description
RepositoryURL	string	The URL of the Git repository.
RepositoryBranch	string	The specific branch to be analyzed.
LanguageExclusions	string	A comma-separated list of languages to exclude.

Sources: client/analysis/analysis.go:19-23, api/routes/analysis.go:87-92

Processing Flow

The ReceiveRequest function follows a strict validation and processing sequence before starting the analysis.

This diagram illustrates the sequence of events when a client posts a new analysis request.

Responses

• 201 Created: The request was accepted, and the analysis has been queued. The X-Request-Id header in the response contains the unique ID for this analysis.
• 400 Bad Request: The request body is not a valid JSON.
• 401 Unauthorized: The provided Husky-Token is invalid or lacks permission for the repository URL.
• 409 Conflict: An analysis for the same repository and branch is already in a running state.
• 500 Internal Server Error: An error occurred during database operations.

Sources: api/routes/analysis.go:91-149

Retrieving Analysis Results (GET /analysis/:id)

This endpoint allows a client to poll for the status and results of a previously submitted analysis using its unique Request ID (RID). The request is handled by the GetAnalysis function.

Sources: api/routes/analysis.go:42-76

Request

• Path Parameter: id (string, required) - The RID returned in the X-Request-Id header of the POST /analysis response.
• Header: Husky-Token (string, required) - An authorization token.

Processing Flow

The GetAnalysis function retrieves the analysis document from the database and performs an authorization check.

This diagram shows the flow for retrieving an analysis result.

Responses

• 200 OK: The request was successful. The body contains the analysis object in JSON format.
• 401 Unauthorized: The provided Husky-Token is invalid or not authorized for the repository associated with the RID.
• 404 Not Found: No analysis with the given RID was found.
• 500 Internal Server Error: An internal error occurred while querying the database.

Sources: api/routes/analysis.go:42-76

Client-Side Workflow

The huskyci-client demonstrates the intended consumption pattern for the analysis API. It first starts an analysis and then enters a monitoring loop, periodically polling the GET endpoint until the analysis is complete.

This flowchart illustrates the client's logic for running and monitoring an analysis.

Data Structures

Analysis Data Model

The Analysis struct is the primary data model for storing and retrieving analysis information. While the exact API-side definition is not present in the provided files, the CLI's Analysis struct offers a clear representation of the data.

Field	Type	Description
ID	string	Unique identifier for the analysis (distinct from RID).
Status	string	The current state of the analysis (e.g., running, finished, error).
Result	Result	A summary of the final outcome.
Errors	[]string	A list of errors encountered during the analysis.
Languages	[]string	Detected programming languages in the codebase.
StartedAt	time.Time	Timestamp when the analysis began.
FinishedAt	time.Time	Timestamp when the analysis concluded.
Vulnerabilities	[]vulnerability.Vulnerability	A slice containing all vulnerabilities found.

Sources: cli/analysis/analysis.go:17-26

Security Test Output

The results from each security tool are parsed and structured. For example, the output from npmaudit and brakeman are unmarshalled into specific structs before being converted into a generic HuskyCIVulnerability format.

NpmAuditOutput

// NpmAuditOutput is the struct that stores all npm audit output
type NpmAuditOutput struct {
	Vulnerabilities      map[string]Vulnerability `json:"vulnerabilities"`
	Metadata        	 Metadata                 `json:"metadata"`
	PackageNotFound 	 bool
}

Sources: api/securitytest/npmaudit.go:15-20

BrakemanOutput

// BrakemanOutput is the struct that holds issues and stats found on a Brakeman scan.
type BrakemanOutput struct {
	Warnings []WarningItem `json:"warnings"`
	IgnoredWarnings []WarningItem `json:"ignored_warnings"`
}

Sources: api/securitytest/brakeman.go:17-21