Integration guide

Overview

This guide walks you through connecting your network infrastructure to VerifyWise Shadow AI detection, from creating your first API key to verifying that events are flowing into the dashboard. There are two integration paths: the REST API (for custom integrations, browser extensions, and SIEM webhooks) and syslog forwarding (for network proxies and firewalls).

Prerequisites

• Admin or Editor role in VerifyWise
• Access to your network proxy, firewall, or SIEM configuration
• Network connectivity from your data source to the VerifyWise server

REST API integration

The REST API is the most flexible integration method. Use it when your data source can make HTTP requests — for example, a SIEM webhook action, a custom script, or a browser extension.

Step 1: Create an API key

1. Navigate to Shadow AI → Settings
2. In the "API keys" section, click "Create API key"
3. Enter a label that identifies the data source (e.g., "Zscaler webhook", "Browser extension prod")
4. Click "Create"
5. Copy the full key immediately and store it securely — it will not be shown again

Step 2: Send events

Send a POST request to the ingestion endpoint with your events. The endpoint accepts batches of up to 10,000 events per request.

Endpoint: POST /api/v1/shadow-ai/events

Headers:

Example request body:

{
  "events": [
    {
      "user_email": "alice@company.com",
      "destination": "chat.openai.com",
      "timestamp": "2026-02-09T14:32:00Z",
      "uri_path": "/v1/chat",
      "http_method": "POST",
      "action": "allowed",
      "department": "Engineering",
      "job_title": "Senior Engineer",
      "manager_email": "bob@company.com"
    }
  ]
}

Required fields: user_email, destination, timestamp. All other fields are optional but improve the accuracy of risk scoring and department-level reporting.

Step 3: Verify ingestion

A successful request returns a 200 response with the number of events ingested and tools matched:

{
  "data": {
    "ingested": 1,
    "tools_matched": 1
  }
}

After sending events, verify they appear in the system:

1. Go to Shadow AI → Insights and check that the summary cards update (unique apps, AI users)
2. Go to Shadow AI → AI tools and confirm the destination domain appears as a detected tool
3. Go to Shadow AI → User activity and confirm the user email appears in the users list

REST API error responses

Syslog integration

Syslog integration is ideal for network proxies and firewalls that natively support syslog forwarding (Zscaler Internet Access, Netskope, Squid proxy). The VerifyWise server runs a TCP syslog listener that receives log lines, parses them using the configured parser, and feeds them into the same event pipeline as the REST API.

Step 1: Verify the syslog listener is running

The syslog listener is controlled by the SHADOW_AI_SYSLOG_PORT environment variable on the VerifyWise server. By default it listens on port 5514. Set the variable to 0 to disable it.

Confirm the listener is running by checking the server logs for the message: Syslog listener started on port 5514. If you do not see it, verify the environment variable is set and the server has been restarted.

Step 2: Add a syslog source in VerifyWise

1. Navigate to Shadow AI → Settings
2. In the "Syslog sources" section, click "Add source"
3. Enter the source identifier — this must be the IP address of the machine that will send syslog messages (e.g., 10.0.1.50). The syslog listener matches incoming connections by source IP.
4. Select the parser type that matches your data source (Zscaler, Netskope, Squid proxy, or Generic key-value)
5. Click "Add"

Step 3: Configure your proxy to forward logs

Configure your network proxy or firewall to send syslog messages over TCP to the VerifyWise server. Below are configuration notes for each supported source.

Zscaler Internet Access

1. In the ZIA admin portal, navigate to Administration → Nanolog Streaming Service
2. Add a new NSS feed or edit an existing one
3. Set the feed output type to Syslog
4. Set the syslog destination to your VerifyWise server IP and port (default 5514), protocol TCP
5. In the log format, include at minimum: user, dst, method, uri, action. Optionally include department for department-level reporting
6. Save and activate the feed

Expected log line format:

user=alice@company.com dst=chat.openai.com method=POST uri=https://chat.openai.com/v1/chat action=allowed department=Engineering

Netskope

1. In the Netskope admin console, navigate to Settings → Tools → SIEM
2. Add a new SIEM profile with type Syslog
3. Set the destination to your VerifyWise server IP and port (default 5514), protocol TCP
4. Set the format to JSON
5. Select the event types to forward (at minimum: page events and application events)
6. Save and enable the profile

Expected log line format (JSON embedded in syslog frame):

{"user":"alice@company.com","url":"https://chat.openai.com/v1/chat","method":"POST","activity":"allowed","department":"Engineering","timestamp":"2026-02-09T14:32:00Z"}

Squid proxy

1. Edit your Squid configuration file (squid.conf)
2. Add or modify the access_log directive to forward to a syslog destination via TCP: access_log tcp://VERIFYWISE_IP:5514
3. Ensure the log format includes the user identity field (%un) — Squid must be configured with authentication (LDAP, Kerberos, or basic) for user emails to be captured
4. Reload the Squid configuration: squid -k reconfigure

Expected log line format (standard Squid access log):

1707489120.000 200 10.0.0.1 TCP_MISS/200 1024 POST https://chat.openai.com/v1/chat alice@company.com DIRECT/chat.openai.com

Generic key-value (CEF-like)

The generic key-value parser handles CEF-style log lines and any source that outputs key=value pairs. Use this for firewalls, DLP systems, or custom log forwarders that do not match the Zscaler, Netskope, or Squid formats.

The parser looks for the following CEF-standard field names:

Example log line:

suser=alice@company.com dhost=chat.openai.com requestMethod=POST act=allowed

Step 4: Verify syslog ingestion

1. After configuring your proxy, generate some test traffic by visiting a known AI tool (e.g., chat.openai.com) through the monitored network
2. Wait 5-10 seconds for the syslog batch to flush (events are batched in 2-second intervals with a batch size of 50)
3. Go to Shadow AI → Insights and verify the summary cards show updated numbers
4. Go to Shadow AI → AI tools and confirm the test domain appears
5. If events do not appear, check the server logs for parse errors: look for messages containing "Syslog parse failed" which indicate a parser mismatch

Troubleshooting

Best practices

• Use descriptive API key labels: Label each key with the source system and environment (e.g., "Zscaler prod", "Browser ext staging") so you can quickly identify and rotate keys
• Include optional fields: The department, job_title, and manager_email fields are not required but significantly improve risk scoring accuracy and enable department-level alerts
• Start with a single source: Integrate one data source first, verify events are flowing, then add additional sources
• Set up alert rules early: Create at least a "New tool detected" rule immediately after integration so you are notified when new AI tools appear in your network
• Monitor the rate limit: If you are ingesting from a high-volume proxy, configure the rate limit in Settings to prevent accidental overload during initial rollout
• Rotate API keys regularly: Revoke and recreate API keys periodically. When rotating, create the new key first, update the data source configuration, then revoke the old key