# Phishing detection

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

Sentinel checks URLs against a list of known phishing sites, both inside submitted text and through a dedicated API. Use it to stop forms, comments and messages that carry phishing links, and to check a single link from your backend.

## How it works

Sentinel downloads the phishing list as the [remote file](/docs/sentinel/v2/configure/remote-files/) `phishing`, by default the ALTCHA directory's `https://directory.altcha.org/phishing.csv.gz`, and checks it for updates daily. The list is a CSV file with a header line and a `url` column, plus the optional columns `phish_id` (or `id`), `target`, `submission_time` and `verified`. A PhishTank export (`online-valid.csv` or `.csv.gz`) has these columns, so you can use it instead. Rows with a `verified` value other than empty or `yes` are skipped.

A URL matches when it equals a listed URL exactly, after removing a trailing `/` (also one right before `?`):

- The comparison is case-sensitive.
- When the full URL isn't listed, Sentinel tries it again without its query string.
- A URL without a scheme is tried with `http://`, then with `https://`.

The list is used in three places:

- **Text classification**: the `URL_PHISHING` rule finds URLs in the `text` of `POST /v2/classifier` and in the form fields of `POST /v2/verify`, including URLs without a scheme and URLs inside markup such as `href="…"`.
- **Email analysis**: the EML rule `LINK_PHISHING` checks link targets in `POST /v2/eml`. See [Email analysis](/docs/sentinel/v2/features/email-analysis/).
- **`POST /v2/phishing`**: checks one URL from your backend.

## Enabling it

The list is enabled by default. These are the keys you are most likely to change:

```toml
[classifier.phishing]
enabled = true
url = "https://directory.altcha.org/phishing.csv.gz"   # or a PhishTank online-valid.csv.gz URL
schedule = "@daily"
max_entries = 100000   # URLs kept from the start of the list
```

With `enabled = false`, the list is never downloaded, `URL_PHISHING` scores `0`, and `POST /v2/phishing` returns `phishing: false` for every URL. Larger downloads than `max_size_mb` (default `10`) fail and the previous list stays in use. See [Classifier lists](/docs/sentinel/v2/reference/configuration/#classifier-lists).

In security groups, `URL_PHISHING` runs with the other text rules whenever text is classified, for example with `classifier.fields` turned on. To turn it off for one group, add it to `classifier.disableRules`. See [Set fields](/docs/sentinel/v2/reference/rules/#classifier).

## Rules & signals

| Rule | Meaning |
| --- | --- |
| `URL_PHISHING` | The text contains one or more URLs on the phishing list. Scores per distinct URL, and a triggered rule makes the classification `BAD`. |
| `LINK_PHISHING` | A link in an analyzed email points to a URL on the phishing list. |

The scores are in [Classifier rules & scores](/docs/sentinel/v2/reference/classifier-rules/#text). The matched URLs are listed in the classifier's `text.phishing`:

```json
{
"data": {
"classification": "BAD",
"text": {
  "phishing": [
    { "url": "https://140bae.senes.at/bncearn", "phishId": "9446249", "target": "Binance", "submittedAt": "2026-06-07T15:01:13Z" }
  ],
  "triggeredRules": ["URL_PHISHING", "URL"],
  …
},
…
}
}
```

`text.phishing` is `[]` when no listed URL is found, or when `URL_PHISHING` is disabled.

## Using the API

Send a URL to `POST /v2/phishing` with a `restricted` or `full` key:

```bash
curl -X POST https://sentinel.example.com/v2/phishing \
-u 'key_…:sec_…' \
-H 'Content-Type: application/json' \
-d '{ "url": "https://140bae.senes.at/bncearn/?ref=mail" }'
```

```json
{
"data": {
"phishing": true,
"url": "https://140bae.senes.at/bncearn",
"phishId": "9446249",
"target": "Binance",
"submittedAt": "2026-06-07T15:01:13Z",
"time": 0.03
}
}
```

`url` is the listed URL that matched; here, the query string was dropped to find it. `phishId`, `target` and `submittedAt` are copied from the list and are `null` when the list has no value. For a URL that isn't listed, `phishing` is `false` and all four fields are `null`. `time` is the lookup duration in milliseconds.

The input `url` is trimmed and must be 1 to 2048 characters; otherwise the response is `400 VALIDATION_ERROR`. A `public` key gets `403 NON_PUBLIC_API_KEY_REQUIRED`. See the [API reference](/sentinel-api-docs-v2.html#tag/phishing/POST/v2/phishing).

## Tuning

- **Check the list is loaded.** Until the first download finishes, nothing matches. Root users see the `phishing` file's status under **Remote Files** in the admin UI, or with `GET /v2/remote-files`.
- **Use your own list.** Point `url` at any CSV with a `url` column, for example a feed from your security team. One list is used at a time.
- **Keep more URLs.** The default `max_entries` keeps the first 100000 URLs; raise it (up to `10000000`) for a larger list.

## Limitations

- Only exact, listed URLs match. A new phishing URL, or a listed site under a different path or host, isn't detected until the list includes it.
- Matching is case-sensitive: `HTTPS://Example.com/login` doesn't match a listed `https://example.com/login`.
- URLs longer than 2048 characters are never listed or matched.

## Related

- [Spam, profanity & injection](/docs/sentinel/v2/features/text-analysis/)
- [Classifier](/docs/sentinel/v2/features/classifier/)
- [Email analysis](/docs/sentinel/v2/features/email-analysis/)
- [Classifier rules & scores: Text](/docs/sentinel/v2/reference/classifier-rules/#text)
- [Remote files & data sources](/docs/sentinel/v2/configure/remote-files/)
- [Classifier lists](/docs/sentinel/v2/reference/configuration/#classifier-lists) in the Configuration reference
