Agent Installation and Configuration

The Wisec agent is a self-contained Go binary designed to run in any CI/CD environment (GitLab CI, GitHub Actions, Jenkins, etc.). It collects build information, generates an immutable event, signs it cryptographically, and sends it to the Wisec API Gateway.

Requirements

• A Linux-based CI/CD runner (e.g., alpine:latest or ubuntu:latest).

• git installed in your CI/CD environment (for collecting commit, branch, and file change data).

• gitleaks installed in your CI/CD environment (for collecting secrets and sensitive data).

• curl to download the agent binary.

• A Wisec account with at least one project created.

• A generated Agent Signing Key (Private Key) from the Wisec dashboard.

Core Agent Integrations

The Wisec agent is built to be "environment-aware" and automatically uses common tools to enrich the data it collects.

• git: The agent uses git commands (git log, git diff) to automatically collect critical information about the commit, author, branch, and which files were changed or deleted. This is essential for providing context to the build event.

• gitleaks: If the agent detects that gitleaks is installed in the environment, it will automatically run it to scan for hardcoded secrets. The results are bundled into the event payload, providing immediate visibility into secret leaks directly within the Wisec dashboard. You can add a .gitleaksignore file to your repository to manage false positives.

1. Download the Agent

The Wisec agent binary is served from a public Google Cloud Storage bucket for easy and reliable access.

curl -L -o wisec-agent https://storage.googleapis.com/wisec-downloads/agent
chmod +x wisec-agent

2. Environment Variables

The agent requires the following environment variables to be configured in your CI/CD pipeline's settings (e.g., GitLab CI/CD Variables, GitHub Actions Secrets). These should be marked as secret/masked variables to prevent accidental exposure.

• WISEC_PROJECT_ID:

  • Purpose: The unique identifier for the project in Wisec where this pipeline's events will be logged.

  • Value: Obtain this from your Wisec dashboard's "Projects" page (in the "Project ID" column) or from the creation confirmation modal.

  • Example: 1 (if it's your first project)

• AGENT_PRIVATE_KEY_HEX:

  • Purpose: The private part of your Ed25519 signing key pair. The agent uses this to cryptographically sign each event, ensuring immutability and authenticity.

  • Value: Generate this from your Wisec dashboard's Settings page, under "Agent Signing Keys". Copy the displayed private key immediately.

  • Example: f0e1d2c3b4a5968778695a4b3c2d1e0f102132435465768798091a2b3c4d5e6f (a long hexadecimal string)

• WISEC_API_ENDPOINT:

  • Purpose: The full URL of the Wisec API Gateway endpoint where pipeline events should be sent.

  • Value: https://app.wisec.io/api/v1/events

Note on WISEC_API_KEY

The WISEC_API_KEY (also generatable from the Settings page) is a separate mechanism intended for future use, primarily for authenticating direct API calls from external applications or scripts to Wisec. It is not currently used by the wisec-agent.

3. Integrate into your CI/CD Script

Once the agent is downloaded and environment variables are set, you can integrate it into your CI/CD pipeline script. Refer to the Quick Start Guide for an example.