Skip to main content
ALTCHA®

Phishing detection

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 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.
  • 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:

[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.

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.

Rules & signals

RuleMeaning
URL_PHISHINGThe text contains one or more URLs on the phishing list. Scores per distinct URL, and a triggered rule makes the classification BAD.
LINK_PHISHINGA link in an analyzed email points to a URL on the phishing list.

The scores are in Classifier rules & scores. The matched URLs are listed in the classifier's text.phishing:

{
  "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:

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" }'
{
  "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.

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.

Start typing to search...

↑ ↓ Navigate ↵ Select