Shadow AI settings

Overview

The Settings page is where you configure data sources, access controls and operational parameters for Shadow AI detection. It's divided into six sections: API keys, syslog sources, data formats, rate limiting, data retention and risk score calculation. Only Admins can manage API keys, syslog sources and the rate limit.

API keys

API keys authenticate events sent to the REST API, for example from a SIEM webhook, a script or a browser extension. Syslog sources do not use these keys; each source has its own key (see below).

Creating a key

1. Click "Create API key"
2. Optionally enter a label (e.g., "Zscaler proxy")
3. Click "Create"
4. Copy the full key immediately, it won't be shown again

Managing keys

The API keys table shows each key's prefix, label, status (Active or Revoked), creation date and last-used date. You can:

• Revoke: Deactivates the key. Integrations using this key will stop working. This cannot be undone. The server you are connected to refuses the key at once; with several backend replicas, the others can accept it for up to 5 minutes.
• Delete: Permanently removes a revoked key from the list. Only revoked keys can be deleted.

Syslog sources

Syslog sources define where network traffic data comes from. Each source has a parser type, a secret key that every log line carries, and an optional allowed sender IP. Only Admins can manage them. The setup steps are in the Integration guide.

A line above the table shows whether the syslog listener is on and where to send logs (port 6514 by default, over TLS or plain TCP). The listener is off until the server operator sets SHADOW_AI_SYSLOG_ENABLED=true. If it is turned on but could not start, the line says so; the server log has the reason. The hosted service does not offer syslog yet.

Parser types

The source table

Source keys

When you add a source, the "Your source key" dialog shows the key once, with a copy button and a ready-made vw_source=<key> line. VerifyWise stores only a hash and the first characters of the key, so it cannot show the key again. If you lose it, click "Regenerate key". The old key stops working at once on the server you used and within 60 seconds on any other replica. Removing a source stops processing events from it.

Data formats

This section documents the exact data formats VerifyWise expects when ingesting Shadow AI events, whether through the REST API or via syslog forwarding.

REST API event schema

Send events via POST /api/v1/shadow-ai/events with a JSON request body containing an events array of up to 10,000 events. Authenticate using the X-API-Key header with a valid API key.

{
  "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"
    }
  ]
}

Syslog format examples

Syslog messages arrive over TCP (TLS by default), newline-delimited or octet-counted, up to 64 KiB each. An RFC 3164 or RFC 5424 header is removed when present. Every line must carry the source key as vw_source=<key> at the start or the end of the line, or as a top-level "vw_source" member when the line is a JSON object. A key anywhere else is ignored. VerifyWise removes the key before parsing and never stores it. Below is one example per parser, with the field added.

Zscaler (key=value)

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

Netskope (JSON-in-syslog)

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

Send the whole object on one line. With newline-delimited framing, a pretty-printed object is split into lines that cannot be read.

Squid (space-delimited)

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 vw_source=YOUR_SOURCE_KEY

Generic key-value (CEF-style)

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

Field mapping

Each parser maps its fields to the normalized event schema. The user must be a valid email address; it is stored in lowercase. For the action, the first word of the value decides: block, deny, drop, reset or reject (and forms such as blocked, denied or dropped) become blocked, and allow, permit, pass or accept (and forms such as allowed or permitted) become allowed, so Blocked by policy is blocked. A negated allow such as Not allowed or disallowed is also blocked. Any other value, including words that only begin with one of these such as password_reset, or no action at all, is stored as allowed. The timestamp comes from the payload field when present, then from the syslog header, then from the time VerifyWise received the line. A timestamp without a time zone is read as UTC; a zone it states (an offset, Z, PST, CEST, also in brackets such as (Tokyo JST)) is used. A zone name VerifyWise does not know, such as IST, makes the payload time unreadable, so send an offset or Z if your source logs in another zone. A timestamp more than a year before the time the line was received, or more than a day after it, is ignored. A destination can be a host name, an IPv4 or IPv6 address (bare or in brackets) or a URL, and is stored in lowercase. A destination of -, N/A or none is skipped and the next field (such as the URL) is used. An email address longer than 255 characters or a destination longer than 512 drops the line, and a department is cut to 255 characters.

Rate limiting

Rate limiting caps how many events your organization can ingest per hour, across the REST API and syslog. It protects the system from a misconfigured data source or a traffic spike. Only Admins can change it. The count is kept in memory by each backend process, so with several backend replicas the effective limit is the setting times the number of replicas.

• Set a number to cap hourly ingestion. Set 0 or leave the field empty for no limit (the default).
• The hour starts with the first event counted, not on the clock hour.
• A REST request that would go over the limit is refused whole with a 429 response. Syslog events over the limit are dropped and show "Over the hourly event limit" on the source.
• A change applies to the REST API at once and to syslog within 30 seconds.

Data retention

Data retention settings control how long different types of Shadow AI data are stored before automatic cleanup. Three categories can be configured independently:

Each period can be 1 to 3,650 days. Cleanup runs once a day, so a change applies at the next run. Raw events are removed by the time of the event, not the time it arrived. Admins can change these periods, and so can a custom role that has the organization admin permission. Each change is recorded in the audit ledger.

Risk score calculation

The bottom of the Settings page explains how the risk score is calculated. Each AI tool receives a score from 0 to 100, recalculated nightly using four weighted factors: