Skip to main content
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
  • gRPC Proxies: Dedicated proxy support for gRPC API calls
  • 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.
  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 on failure.
  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"

# 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"
  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
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

​
gRPC Proxy Configuration

For gRPC API calls, use the dedicated --grpc-proxy option.

​
CLI Option

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

​
Environment Variable

export grpc_proxy="http://<ip-addr>:<port>"
scanoss-py scan -o results.json /path/to/project

​
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

For the HTTP/REST API (requests library): 
export REQUESTS_CA_BUNDLE=/path/to/company-ca.pem
scanoss-py scan -o results.json /path/to/project
For the gRPC API: 
export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=/path/to/ca-bundle.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.