Skip to main content

​
Why Use a Proxy with SCANOSS?

​
Centralised API Key Management

The proxy automatically injects the SCANOSS API key, eliminating the need to distribute it to developer machines. This ensures secure, centralised control over API access.

​
Security & Access Control

  • Enforce corporate policies with centralised traffic monitoring and filtering
  • Restrict access to authorised internal systems
  • Maintain full visibility into all API interactions

​
Usage Tracking & Logging

  • Monitor scan activity by team or project
  • Analyse API usage patterns
  • Preserve detailed audit logs for compliance

​
Network Architecture Requirements

Supports enterprise network policies requiring:
  • Centralised outbound traffic control
  • Internal certificate-based communication
  • Deep packet inspection and filtering

​
Prerequisites

Before you begin, you’ll need:
  • Caddy: Lightweight reverse proxy that securely injects your SCANOSS API key into outgoing API requests.
  • SCANOSS API key: Enables access to SCANOSS enterprise features.

​
Proxy Configuration

Follow the steps below to configure Caddy as a reverse proxy that injects your SCANOSS API key into outgoing requests. Windows
  1. Create a new folder to store Caddy and its configuration
  2. Inside that folder, create a new file named Caddyfile
  3. Add the following configuration:
:1980 {
    reverse_proxy https://api.scanoss.com {
        header_up x-api-key "YOUR_API_KEY_HERE"
        header_up Host api.scanoss.com
    }
}
  1. Replace YOUR_API_KEY_HERE with your actual SCANOSS API key
  2. Save and Close
macOS/Linux
  1. Create a new folder to store Caddy and its configuration
  2. Inside that folder, create a new file named Caddyfile
  3. Add the following configuration:
:1980 {
    reverse_proxy https://api.scanoss.com {
        header_up x-api-key "YOUR_API_KEY_HERE"
        header_up Host api.scanoss.com
    }
}
  1. Replace YOUR_API_KEY_HERE with your actual SCANOSS API key
  2. Save and Close
You can change port 1980 to any available port (for example, 8080 or 8888). Ensure the chosen port is not already in use by another service.

​
HTTPS Configuration

​
Automatic HTTPS with a Domain

If you have a domain name, Caddy can automatically obtain and renew SSL certificates: 
proxy.example.com {
    reverse_proxy https://api.scanoss.com {
        header_up x-api-key "YOUR_API_KEY_HERE"
        header_up Host api.scanoss.com
    }
}
Replace proxy.example.com with your actual domain. Caddy will automatically:
  • Obtain a Let’s Encrypt certificate
  • Handle HTTPS on port 443
  • Redirect HTTP to HTTPS

​
Self-Signed Certificate for Internal Use

For internal/local deployments without a domain, use a self-signed certificate: 
localhost:1980 {
    tls internal

    reverse_proxy https://api.scanoss.com {
        header_up x-api-key "YOUR_API_KEY_HERE"
        header_up Host api.scanoss.com
    }
}
Or for a specific IP: 
https://192.168.1.100:1980 {
    tls internal

    reverse_proxy https://api.scanoss.com {
        header_up x-api-key "YOUR_API_KEY_HERE"
        header_up Host api.scanoss.com
    }
}
Self-signed certificates will trigger security warnings in browsers and applications. You may need to add the certificate to your system’s trusted certificates or configure your tools to accept self-signed certificates.

​
Custom Certificate Files

If you have your own certificate and key files: 
:1980 {
    tls /path/to/cert.pem /path/to/key.pem

    reverse_proxy https://api.scanoss.com {
        header_up x-api-key "YOUR_API_KEY_HERE"
        header_up Host api.scanoss.com
    }
}
When using HTTPS, update your client configurations to use https:// instead of http://

​
Running Caddy

Once the Caddyfile is configured, you can start the proxy in either interactive or background mode.

​
Interactive Mode

Run Caddy in the foreground to verify your configuration and observe logs in real time. Windows Open PowerShell, navigate to the folder and start Caddy: 
caddy run --config Caddyfile
macOS/Linux Open Terminal, navigate to the folder and start Caddy: 
sudo caddy run --config Caddyfile

​
Background Mode

Run Caddy as a background process so it continues running after you close the terminal. Windows Open PowerShell, navigate to the folder and start Caddy: 
caddy start --config Caddyfile
macOS/Linux Open Terminal, navigate to the folder and start Caddy: 
sudo caddy start --config Caddyfile

​
Running as a systemd Service (Optional)

Run Caddy as a systemd service to ensure it starts automatically on boot and restarts if it crashes. macOS/Linux
  1. Create a systemd service file:
sudo nano /etc/systemd/system/caddy-proxy.service
  1. Add the following configuration:
[Unit]
Description=Caddy API Proxy
After=network.target

[Service]
ExecStart=/usr/bin/caddy run --config /etc/caddy/Caddyfile
Restart=always
User=caddy
Group=caddy

[Install]
WantedBy=multi-user.target
Update /etc/caddy/Caddyfile to match the actual path to your Caddyfile. Update /usr/bin/caddy if Caddy is installed in a different location (check with which caddy).
  1. Enable and start the service:
sudo systemctl daemon-reload
sudo systemctl enable caddy-proxy
sudo systemctl start caddy-proxy
  1. Check the service status:
sudo systemctl status caddy-proxy

​
Running as a Windows Service (Optional)

Run Caddy as a Windows service to ensure it starts automatically on boot and restarts if it crashes. Windows
  1. Download and install NSSM
  2. Open PowerShell as Administrator and navigate to the NSSM directory
  3. Install Caddy as a service:
nssm install CaddyProxy "C:\path\to\caddy.exe" "run --config C:\path\to\Caddyfile"
Replace C:\path\to\caddy.exe with the actual path to your Caddy executable. Replace C:\path\to\Caddyfile with the actual path to your Caddyfile.
  1. Configure the service (optional):
# Set the startup directory
nssm set CaddyProxy AppDirectory "C:\path\to\caddy\folder"

# Set service to restart on failure
nssm set CaddyProxy AppStdout "C:\path\to\logs\caddy-output.log"
nssm set CaddyProxy AppStderr "C:\path\to\logs\caddy-error.log"
  1. Start the service:
nssm start CaddyProxy
  1. Verify the service is running:
nssm status CaddyProxy
Managing the Windows Service: 
# Stop the service
nssm stop CaddyProxy

# Restart the service
nssm restart CaddyProxy

# Remove the service
nssm remove CaddyProxy confirm
Or use the Windows Services manager (services.msc) to manage the service through the GUI.

​
Stopping Caddy

caddy stop

​
Use Caddy with SBOM Workbench

By using Caddy as a local proxy, SBOM Workbench can connect to the ScanOSS API without storing your API key in the application.
  1. Open SBOM Workbench
  2. Go to File → Settings → ”+”
  3. For API URL, enter: 
    http://<your-server-ip>:1980
    For HTTP connections, use http://localhost:1980 if running locally. For HTTPS connections, use https://localhost:1980 or https://<your-domain>
  4. Click Add → Save
  5. Select the API connection you just added when scanning a project

​
Use Caddy with SCANOSS-PY

Once your Caddy proxy is running, SCANOSS-PY can be used without supplying an API key. All requests go through Caddy, which injects the key automatically. 
# HTTP
scanoss-py scan --apiurl "http://localhost:1980" /path/to/project

# HTTPS
scanoss-py scan --apiurl "https://localhost:1980" /path/to/project

​
Troubleshooting

​
Port conflicts

If Caddy fails to start it usually means the default admin API port is already in use. You can fix this by disabling the admin API in your Caddyfile: 
{
  admin off
}
Place this at the top of your Caddyfile before any site definitions.

​
Stopping existing Caddy instances

If the conflict persists, check for running Caddy processes and stop them: Windows: 
taskkill /IM caddy.exe /F
Linux/macOS: 
# Stop all running Caddy processes
pkill caddy

# Or, if running as a systemd service
sudo systemctl stop caddy