> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Proxy and Certificate Options

> Configure HTTP/HTTPS proxies, PAC (Proxy Auto-Config), custom SSL certificates, and reverse proxy with API key injection for corporate networks and secure environments.

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:

```bash theme={null}
scanoss-py scan --proxy "http://<ipaddr>:<port>" -o results.json /path/to/project
```

### Environment Variables

Set proxy environment variables for automatic detection:

```bash theme={null}
# 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](https://caddyserver.com/): A reverse proxy that injects your SCANOSS API key into
  outgoing API requests
* [SCANOSS API key](https://www.scanoss.com/try-it-now): 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:

```caddyfile theme={null}
: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:

```caddyfile theme={null}
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:

```caddyfile theme={null}
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:

```caddyfile theme={null}
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:

```caddyfile theme={null}
: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:

```bash theme={null}
caddy run --config Caddyfile
```

**macOS/Linux**

Open Terminal, navigate to the folder, and run:

```bash theme={null}
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:

```bash theme={null}
caddy start --config Caddyfile
```

**macOS/Linux**

Open Terminal, navigate to the folder, and run:

```bash theme={null}
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:

```bash theme={null}
sudo nano /etc/systemd/system/caddy-proxy.service
```

2. Add the following configuration:

```ini theme={null}
[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`).

3. Enable and start the service:

```bash theme={null}
sudo systemctl daemon-reload
sudo systemctl enable caddy-proxy
sudo systemctl start caddy-proxy
```

4. Check the service status:

```bash theme={null}
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](https://nssm.cc/download)
2. Open PowerShell as Administrator and navigate to the NSSM directory
3. Install Caddy as a service:

```powershell theme={null}
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`.

4. Configure the service (optional):

```powershell theme={null}
# 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"
```

5. Start the service:

```powershell theme={null}
nssm start CaddyProxy
```

6. Verify the service is running:

```powershell theme={null}
nssm status CaddyProxy
```

**Managing the Windows Service**

```powershell theme={null}
# 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

```bash theme={null}
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.

```bash theme={null}
# 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:**

```bash theme={null}
# 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`:

```json theme={null}
{
  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**

```powershell theme={null}
taskkill /IM caddy.exe /F
```

**Linux/macOS**

```bash theme={null}
# 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

```bash theme={null}
# Automatically discover and use the system PAC configuration
scanoss-py scan --pac auto -o results.json /path/to/project
```

### Specify a PAC File

```bash theme={null}
# 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:

```bash theme={null}
# 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

```bash theme={null}
# Use a custom CA certificate bundle
scanoss-py scan --ca-cert /path/to/company-ca.pem -o results.json /path/to/project
```

### Environment Variables

```bash theme={null}
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:

```bash theme={null}
scanoss-py utils certloc
```

### Download Server Certificates

SCANOSS provides a utility to download SSL certificates from servers:

```bash theme={null}
# 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:

```bash theme={null}
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.