Quick Start

This guide will get you up and running with Wisec in less than 5 minutes.

1. Create an Account and Your First Project

First, create a Wisec account. Your organization and your first project will be set up automatically. You can create more projects from the Projects page in the dashboard.

2. Get your Project ID and Agent Signing Key

To connect your CI/CD pipeline to Wisec, you need two pieces of information:

Your Project ID:
1. Go to the Projects page.
2. Click on "Add New Project" or select an existing one.
3. After creating a new project, a popup will display your Project ID. You can also find it in the "Project ID" column on the Projects page.
Your Agent Signing Key (Private Key):
1. Go to the Settings page.
2. Locate the "Agent Signing Keys" section.
3. Click the "Generate New Signing Key" button.
4. A Private Key will be displayed. Copy this key immediately and store it securely. This is the only time it will be shown. This key is your agent's identity for signing events.

3. Configure your CI/CD Pipeline

In your CI/CD pipeline configuration (e.g., .gitlab-ci.yml), you will need to set up the following environment variables:

WISEC_PROJECT_ID: The ID of your project obtained in Step 2.
AGENT_PRIVATE_KEY_HEX: The private key you copied from the Settings page in Step 2.
WISEC_API_ENDPOINT: The full URL of your Wisec API event endpoint. This should be https://app.wisec.io/api/v1/events.

Example for GitLab CI

# .gitlab-ci.yml example for Wisec integration

variables:
  # Set these in your GitLab CI/CD project's settings (Settings > CI/CD > Variables)
  # WISEC_PROJECT_ID: "YOUR_PROJECT_ID_FROM_DASHBOARD"
  # AGENT_PRIVATE_KEY_HEX: "YOUR_AGENT_PRIVATE_KEY_HEX_FROM_DASHBOARD"
  # WISEC_API_ENDPOINT: "https://app.wisec.io/api/v1/events"

# Add a stage for security scanning (optional, adjust as needed)
stages:
  - build
  - test
  - security

scan_with_wisec:
  stage: security
  image: alpine:latest # Use an image with git installed, or install it
  before_script:
    - apk add --no-cache git curl tar # Ensure all tools are available
    - echo "Downloading gitleaks..."
    - wget https://github.com/gitleaks/gitleaks/releases/download/v8.18.2/gitleaks_8.18.2_linux_x64.tar.gz
    - tar -xzf gitleaks_8.18.2_linux_x64.tar.gz
    - chmod +x gitleaks
    - mv gitleaks /usr/local/bin/
    - echo "Downloading wisec-agent..."
    - curl -L -o wisec-agent https://storage.googleapis.com/wisec-downloads/agent
    - chmod +x wisec-agent
  script:
    # Run the agent (it automatically uses environment variables)
    - ./wisec-agent
  allow_failure: true # Allow pipeline to pass even if agent reports issues
  only:
    - master
    - merge_requests

Integrating Gitleaks for Secret Scanning

The wisec-agent is designed to automatically detect and use gitleaks for scanning your repository for hardcoded secrets. This is a critical security check.

Gitleaks Execution: The before_script in the example above already handles the download and installation of gitleaks. The wisec-agent will then automatically run it during its execution.

Handling False Positives with .gitleaksignore: It's common for secret scanners to flag non-sensitive information, such as example keys, test data, or file paths that look like secrets. To prevent these false positives from creating noise in your Wisec dashboard, you should create a .gitleaksignore file at the root of your repository.

The agent will automatically detect and use this file.

Example .gitleaksignore file:

# .gitleaksignore

# Ignore specific files by path
/docs/examples/config.yaml
/test/fixtures/fake_keys.json

# Ignore a specific commit hash that is known to contain a (now revoked) key
a89ed098a76b1f3c4de4b8c82b13c753b3687311

# Ignore a specific secret value that is a known false positive
# (Use with caution, as this will ignore this secret everywhere)
"example-api-key-12345"

# Ignore secrets in this file only by its ID. Get the ID from the gitleaks report.
allowlist:
  - file: src/config/settings.py
    description: "Ignore placeholder AWS key"
    secrets:
      - "AKIAXXXXXXXXXXXXXXXX"

By managing a .gitleaksignore file, you can ensure that the "Hardcoded Secret" alerts in Wisec are relevant and actionable.

4. View Results in Your Dashboard

Once your pipeline runs, events will start appearing in your Wisec dashboard on the Dashboard and Builds pages.