Proxy and Certificate Options

SCANOSS supports flexible proxy and SSL certificate configurations to accommodate corporate networks, air-gapped environments, and secure infrastructures. SCANOSS provides multiple methods to configure network connectivity:

HTTP/HTTPS Proxies: Route traffic through corporate proxy servers
PAC (Proxy Auto-Config): Automatic proxy discovery and configuration
Custom SSL Certificates: Use organisation-specific CA certificates
Certificate Validation Control: Disable certificate validation in testing environments
Reverse Proxy with API Key Injection: Centralised API key management for enterprise deployments

HTTP/HTTPS Proxy Configuration

CLI Option

Use the --proxy flag to specify a proxy server:

scanoss-py scan --proxy "http://<ipaddr>:<port>" -o results.json /path/to/project

Environment Variables

Set proxy environment variables for automatic detection:

# HTTP and HTTPS proxy
export https_proxy="http://<ip-addr>:<port>"
export http_proxy="http://<ip-addr>:<port>"

# Run scan without --proxy flag
scanoss-py scan -o results.json /path/to/project

Reverse Proxy with API Key Injection

A reverse proxy acts as an intermediary between your application and the SCANOSS API server, automatically injecting your API key into requests.

Why Use a Reverse Proxy?

Centralised API Key Management The proxy automatically injects the SCANOSS API key, removing the need to distribute it to individual developer machines. This provides centralised control over API access. Security and 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 and 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 that require:

Centralised outbound traffic control
Internal certificate-based communication
Deep packet inspection and filtering

Prerequisites

Before you begin, you will need:

Caddy: A reverse proxy that injects your SCANOSS API key into outgoing API requests
SCANOSS API key: Required for 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. The Caddyfile configuration is the same on all platforms. Create a folder to store Caddy and its configuration, then create a file named Caddyfile inside it with the following content:

:1980 {
    reverse_proxy https://api.scanoss.com {
        header_up x-api-key "YOUR_API_KEY_HERE"
        header_up Host api.scanoss.com
    }
}

Replace YOUR_API_KEY_HERE with your actual SCANOSS API key and save the file.

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 or 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 address:

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 certificate store, 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 run:

caddy run --config Caddyfile

macOS/Linux Open Terminal, navigate to the folder, and run:

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 run:

caddy start --config Caddyfile

macOS/Linux Open Terminal, navigate to the folder, and run:

sudo caddy start --config Caddyfile

Running as a systemd Service (Linux only)

Run Caddy as a systemd service to ensure it starts automatically on boot and restarts on failure.

Create a systemd service file:

sudo nano /etc/systemd/system/caddy-proxy.service

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).

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable caddy-proxy
sudo systemctl start caddy-proxy

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 on failure.

Download and install NSSM
Open PowerShell as Administrator and navigate to the NSSM directory
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.

Configure the service (optional):

# Set the startup directory
nssm set CaddyProxy AppDirectory "C:\path\to\caddy\folder"

# Configure output logging
nssm set CaddyProxy AppStdout "C:\path\to\logs\caddy-output.log"
nssm set CaddyProxy AppStderr "C:\path\to\logs\caddy-error.log"

Start the service:

nssm start CaddyProxy

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

Alternatively, use the Windows Services manager (services.msc) to manage the service via the GUI.

Stopping Caddy

caddy stop

Using SCANOSS-PY with a Reverse Proxy

Once Caddy is running, SCANOSS-PY can be used without supplying an API key directly. All requests are routed 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

Using a remote proxy server:

# HTTP connection
scanoss-py scan --apiurl "http://<your-server-ip>:1980" /path/to/project

# HTTPS connection with domain
scanoss-py scan --apiurl "https://proxy.example.com" /path/to/project

Troubleshooting Caddy

Port Conflicts

If Caddy fails to start, it is usually because the default admin API port is already in use. You can resolve this by disabling the admin API in your Caddyfile:

{
  admin off
}

Place this block 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

PAC (Proxy Auto-Config)

SCANOSS supports automatic proxy configuration using PAC files.

What is PAC?

PAC (Proxy Auto-Config) files contain JavaScript functions that automatically determine the correct proxy server for each URL. Organisations use PAC files for dynamic proxy configuration across varied network environments.

Enable PAC Auto-Discovery

# Automatically discover and use the system PAC configuration
scanoss-py scan --pac auto -o results.json /path/to/project

Specify a PAC File

# Local PAC file
scanoss-py scan --pac file://proxy.pac -o results.json /path/to/project

# Remote PAC file (HTTP/HTTPS URL)
scanoss-py scan --pac https://path.to/proxy.pac -o results.json /path/to/project

Test PAC Configuration

Use the pac-proxy utility to test your PAC configuration:

# Test PAC auto-discovery
scanoss-py utils pac-proxy --pac auto --url https://api.osskb.org

# Test a specific PAC file
scanoss-py utils pac-proxy --pac https://path.to/proxy.pac --url https://api.osskb.org

# Test a local PAC file
scanoss-py utils pac-proxy --pac file://proxy.pac --url https://api.osskb.org

Custom SSL Certificates

Configure custom CA certificates for organisations using internal certificate authorities.

CLI Option

# Use a custom CA certificate bundle
scanoss-py scan --ca-cert /path/to/company-ca.pem -o results.json /path/to/project

Environment Variables

export REQUESTS_CA_BUNDLE=/path/to/company-ca.pem
scanoss-py scan -o results.json /path/to/project

Find the System Certificate Location

Use the certloc utility to find your system’s CA certificate location:

scanoss-py utils certloc

Download Server Certificates

SCANOSS provides a utility to download SSL certificates from servers:

# Download a certificate from the default port (443)
scanoss-py utils cert-download --hostname <hostname>

Certificate Validation for HTTPS Proxies

When using HTTPS connections with self-signed certificates (common in internal proxy deployments), you may need to handle certificate validation explicitly. Using Custom Certificates with a Reverse Proxy Provide your proxy’s certificate using the --ca-cert option:

scanoss-py scan --apiurl "https://localhost:1980" --ca-cert /path/to/proxy-cert.pem /path/to/project

Self-Signed Certificates Self-signed certificates will trigger security warnings. You may need to:

Add the certificate to your system’s trusted certificate store
Configure SCANOSS-PY to accept the certificate using --ca-cert
Set the REQUESTS_CA_BUNDLE environment variable

Security Note: Only disable certificate verification in trusted, controlled environments. Always use valid certificates issued by a recognised CA in production.

Documentation

Links

HTTP/HTTPS Proxy Configuration

CLI Option

Environment Variables

Reverse Proxy with API Key Injection

Why Use a Reverse Proxy?

Prerequisites

Proxy Configuration

HTTPS Configuration

Automatic HTTPS with a Domain

Self-Signed Certificate for Internal Use

Custom Certificate Files

Running Caddy

Interactive Mode

Background Mode

Running as a systemd Service (Linux only)

Running as a Windows Service (Optional)

Stopping Caddy

Using SCANOSS-PY with a Reverse Proxy

Troubleshooting Caddy

Port Conflicts

Stopping Existing Caddy Instances

PAC (Proxy Auto-Config)

What is PAC?

Enable PAC Auto-Discovery

Specify a PAC File

Test PAC Configuration

Custom SSL Certificates

CLI Option

Environment Variables

Find the System Certificate Location

Download Server Certificates

Certificate Validation for HTTPS Proxies

​HTTP/HTTPS Proxy Configuration

​CLI Option

​Environment Variables

​Reverse Proxy with API Key Injection

​Why Use a Reverse Proxy?

​Prerequisites

​Proxy Configuration

​HTTPS Configuration

​Automatic HTTPS with a Domain

​Self-Signed Certificate for Internal Use

​Custom Certificate Files

​Running Caddy

​Interactive Mode

​Background Mode

​Running as a systemd Service (Linux only)

​Running as a Windows Service (Optional)

​Stopping Caddy

​Using SCANOSS-PY with a Reverse Proxy

​Troubleshooting Caddy

​Port Conflicts

​Stopping Existing Caddy Instances

​PAC (Proxy Auto-Config)

​What is PAC?

​Enable PAC Auto-Discovery

​Specify a PAC File

​Test PAC Configuration

​Custom SSL Certificates

​CLI Option

​Environment Variables

​Find the System Certificate Location

​Download Server Certificates

​Certificate Validation for HTTPS Proxies

HTTP/HTTPS Proxy Configuration

CLI Option

Environment Variables

Reverse Proxy with API Key Injection

Why Use a Reverse Proxy?

Prerequisites

Proxy Configuration

HTTPS Configuration

Automatic HTTPS with a Domain

Self-Signed Certificate for Internal Use

Custom Certificate Files

Running Caddy

Interactive Mode

Background Mode

Running as a systemd Service (Linux only)

Running as a Windows Service (Optional)

Stopping Caddy

Using SCANOSS-PY with a Reverse Proxy

Troubleshooting Caddy

Port Conflicts

Stopping Existing Caddy Instances

PAC (Proxy Auto-Config)

What is PAC?

Enable PAC Auto-Discovery

Specify a PAC File

Test PAC Configuration

Custom SSL Certificates

CLI Option

Environment Variables

Find the System Certificate Location

Download Server Certificates

Certificate Validation for HTTPS Proxies