> ## 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 Pass Configuration

> A proxy is a server that acts as an intermediary between your application and another server. Think of it like a translator or messenger.

## 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](https://caddyserver.com/): Lightweight reverse proxy that securely injects your SCANOSS API key into outgoing API requests.
* [SCANOSS API key](https://www.scanoss.com/try-it-now): 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:

```css theme={null}
:1980 {
    reverse_proxy https://api.scanoss.com {
        header_up x-api-key "YOUR_API_KEY_HERE"
        header_up Host api.scanoss.com
    }
}
```

4. Replace `YOUR_API_KEY_HERE` with your actual SCANOSS API key
5. 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:

```css theme={null}
:1980 {
    reverse_proxy https://api.scanoss.com {
        header_up x-api-key "YOUR_API_KEY_HERE"
        header_up Host api.scanoss.com
    }
}
```

4. Replace `YOUR_API_KEY_HERE` with your actual SCANOSS API key
5. 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:

```css 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/local deployments without a domain, use a self-signed certificate:

```css 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:

```css 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 certificates or configure your tools to accept self-signed certificates.

### Custom Certificate Files

If you have your own certificate and key files:

```css 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 start Caddy:

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

**macOS/Linux**

Open Terminal, navigate to the folder and start Caddy:

```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 start Caddy:

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

**macOS/Linux**

Open Terminal, navigate to the folder and start Caddy:

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

```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 if it crashes.

**Windows**

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"

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

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
```

Or use the Windows Services manager (`services.msc`) to manage the service through the GUI.

### Stopping Caddy

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

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

```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
```

## 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`:

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

```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
```