Skip to main content
ALTCHA®

Outbound proxy & air-gapped deployments

Run Sentinel where outbound internet access is restricted, either through a proxy or with no access at all. Sentinel doesn't need the internet to start or to serve its API, but several features download data, and some of those downloads are on by default.

Without internet access and without the changes on this page, those downloads fail on every scheduled run, log warnings, and raise download_failures alerts. You either route them through a proxy, point them at an internal mirror, or turn them off.

Outbound connections

With the default configuration, Sentinel connects to three hosts:

HostUsed byWhenTurn off or redirect with
directory.altcha.orgThe six classifier lists, [eml.malicious_hashes], [web_bot_auth], and the 15 threat sources seeded on first bootIn the background at startup, then on each list's scheduleenabled = false or url per list; [threats] seed_defaults; each threat source's url
altcha.orgThe release feed ([releases])At startup, every interval (default 6h), and in the background on GET /v2/releases when the last attempt is over an hour old[releases] enabled = false, or url
eu.altcha.orgThe admin UI's AI assistant ([assistant])Only when a user asks the assistant[assistant] enabled = false, or url

Everything else connects only when you configure it:

HostUsed byAir-gapped alternative
license.altcha.org[license] key (online activation and daily refresh)[license] file; see License
download.maxmind.com, ipinfo.iomaxmind and ipinfo-mmdb IP resolver providers with a urlA local .mmdb with path
ip-api.com, pro.ip-api.com, api.ipstack.com, api.ipinfo.io, ipinfo.ioip-api, ipstack, and ipinfo IP resolver providersRemove them; use a local .mmdb
huggingface.co[similarity] provider = "local" model and tokenizer downloads[similarity.local] model_path and tokenizer_path
api.openai.com[similarity] provider = "openai"[similarity.openai] url of an internal OpenAI-compatible server (Ollama, vLLM, TEI)
api.typesafe.ai, openrouter.ai[classifier.ai] (AI decider)[classifier.ai] url of an internal endpoint, or provider = "none" (the default)
fcm.googleapis.com, push.services.mozilla.com, push.apple.com, notify.windows.comWeb push of alerts ([alerts.push]), to the push services in users' subscriptionsLeave [alerts.push] subject unset; use webhooks or email
Your own hostsThe database, Redis, ClickHouse, object storage, LDAP, OAuth issuers, SMTP, alert webhooks, the OTLP collector—

The admin UI loads all of its files, including the API reference, from Sentinel itself.

Use an outbound proxy

If your network has an egress proxy, you can keep the defaults and send outbound HTTP through it. Sentinel reads the standard proxy variables from its environment, like curl:

VariableApplies to
HTTPS_PROXYRequests to https:// URLs
HTTP_PROXYRequests to http:// URLs
ALL_PROXYBoth, when the scheme has no variable of its own
NO_PROXYComma-separated hosts (subdomains included), IPs, and CIDRs that connect directly; * disables the proxy

Lowercase names (https_proxy, …) work too. The proxy URL can use http, https, socks4, socks4a, socks5, or socks5h (the proxy resolves host names), and may include credentials:

docker run -d --name sentinel \
  -e HTTPS_PROXY='http://proxy.corp.example:3128' \
  -e NO_PROXY='localhost,127.0.0.1,10.0.0.0/8' \
  -p 3000:3000 \
  -v "$PWD/sentinel.toml:/home/nonroot/sentinel.toml:ro" \
  -v "$PWD/secrets:/run/secrets:ro" \
  -v sentinel-data:/home/nonroot/data \
  ghcr.io/altcha-org/sentinel:2.0.0-beta.1

The proxy applies to every outbound HTTP client: remote files, the release feed, the assistant, the license server, IP lookup APIs, AI and embedding APIs, OAuth, alert webhooks, web push, object storage, ClickHouse, an ExotDB server, and OTLP export. SMTP ([alerts.email]), LDAP, and Redis aren't HTTP and always connect directly, and so do SQL database connections. Add internal HTTP services, such as ClickHouse, MinIO, or webhook receivers, to NO_PROXY. A proxy URL that doesn't parse is ignored, and requests go direct.

At startup, Sentinel logs the proxy in effect, without credentials:

INFO altcha_sentinel::outbound_proxy: outbound HTTP proxy http="direct" https="http://proxy.corp.example:3128" no_proxy="localhost,127.0.0.1,10.0.0.0/8"

On macOS and Windows, the system proxy settings also apply to a scheme without a variable. The healthcheck command ignores the proxy variables.

Trust a private CA

When outbound TLS goes to servers with certificates from an internal CA, or through a TLS-intercepting proxy, add that CA with the top-level tls_extra_ca_certs key. It takes one or more PEM certificates, trusted next to the system CA store:

tls_extra_ca_certs = "${file:/etc/sentinel/extra-ca.pem}"   # top level, before any [table]

Every outbound TLS connection trusts it: the HTTP clients listed above, OTLP, SMTP, LDAP, the database, Redis, and an ExotDB server. Two exceptions:

  • A per-connection CA replaces it. [auth.ldap] tls_ca, and sslrootcert or ssl-ca in [database] url, replace both the system store and tls_extra_ca_certs for that connection. Include your internal CA in that bundle too.
  • Oracle doesn't use it. Oracle connections are verified by the Oracle Instant Client, configured the Oracle way; see Oracle TLS.

Invalid PEM stops startup (tls_extra_ca_certs: no PEM certificate found), and doctor --config-only reports it. A valid bundle is logged at startup:

INFO altcha_sentinel: tls_extra_ca_certs: extra CA certificates trusted count=1

Mirror the lists

To keep the classification lists, malicious hashes, and Web Bot Auth keys without internet access, copy them to an internal HTTP server and point each list's url at it. A scheduled job on a host with internet access can fetch them:

for list in disposable-email-domains free-email-domains trusted-free-email-providers \
  email-privacy-relays user-agents phishing malicious-file-hashes web-bot-auth; do
  curl -fsSL -o "/srv/mirror/altcha/$list.csv.gz" "https://directory.altcha.org/$list.csv.gz"
done
[classifier.disposable]
url = "https://mirror.example.internal/altcha/disposable-email-domains.csv.gz"

[web_bot_auth]
url = "https://mirror.example.internal/altcha/web-bot-auth.csv.gz"

Keep these points in mind:

  • Keep the files and their .csv.gz names unchanged. A URL whose path ends in .csv.gz is read in the directory's format (header line dropped) on any host. Sentinel keeps the .csv file from the gzip, so a gzip you create yourself must store a name ending in .csv, or no name at all (gzip -n).
  • Serve ETag or Last-Modified. Scheduled checks then download only lists that changed. Without either header, every check downloads the list again.
  • Authentication is up to you. The request signature Sentinel sends to directory.altcha.org isn't sent to other hosts.
  • Threat sources are stored in the database, not in sentinel.toml. Change each one's URL under Threat Intelligence or with PATCH /v2/threat-sources/<id> and {"url": "…"}.

How checks and downloads work is described in Remote files & data sources.

License

Use a license file. It's verified offline and never contacts the license server. Create the license request with altcha-sentinel license request, which needs only the database, then create the file from a connected machine. The steps are in Offline license file.

Don't use an online key ([license] key) without access to the license server. Its license must be refreshed regularly; when the refresh deadline passes, the status becomes refresh_overdue and the functional API stops. To move a deployment that was activated online, replace [license] key with [license] file and restart.

Leave [license] server unset. Sentinel contacts it only when a key is set.

Checklist for an air-gapped node

This configuration turns off every default outbound connection. Add your listeners, database, secrets, and other settings as usual:

[license]
file = "/run/secrets/sentinel_license.json"   # offline license file

[threats]
seed_defaults = false                 # only takes effect before the first start

# Each list: enabled = false, or url = "<internal mirror>"
[classifier.disposable]
enabled = false
[classifier.free_providers]
enabled = false
[classifier.trusted_providers]
enabled = false
[classifier.privacy_relays]
enabled = false
[classifier.user_agents]
enabled = false
[classifier.phishing]
enabled = false

[eml.malicious_hashes]
enabled = false

[web_bot_auth]
enabled = false

[releases]
enabled = false

[assistant]
enabled = false

Then check the rest of your configuration:

  • Don't configure internet-hosted providers: no IP lookup APIs, .mmdb files by path instead of url, [similarity.local] model_path and tokenizer_path instead of downloads, and internal URLs for [classifier.ai] and [similarity.openai]. All of these are off by default.
  • Know what a disabled list costs. Its rule scores 0. With [web_bot_auth] off, the agent condition never matches. Without threat sources, only manual and automatic threat entries match the threat condition.
  • Keep [alerts.download_failures] on. With every download off or mirrored, it only fires when a mirror fails.

DNS

Sentinel needs no DNS server of its own. The classifier's MX and _dmarc lookups and the authentication of POST /v2/eml use the host's resolver (/etc/resolv.conf):

  • With no usable resolver, Sentinel starts with a warning, every lookup fails at once, and the email rules see no record.
  • With an internal resolver that can't answer for internet domains, negative answers are cached for [classifier] dns_cache_ttl (default 1h), and timeouts or SERVFAIL for 30 seconds at most, so a resolver that drops queries costs each domain one dns_timeout per 30 seconds, not one per request.

To skip the lookups, disable the email rules that use them in the security group's classifier.disableRules.

Verify it works

Validate the file before you deploy it, in a one-off container with the same mounts as the server:

docker run --rm \
  -v "$PWD/sentinel.toml:/home/nonroot/sentinel.toml:ro" \
  -v "$PWD/secrets:/run/secrets:ro" \
  ghcr.io/altcha-org/sentinel:2.0.0-beta.1 doctor --config-only
altcha-sentinel 2.0.0-beta.1 doctor, config: sentinel.toml

config
  ok    config.file   Loaded sentinel.toml.
  ok    config.valid  The configuration passes the startup checks.

2 ok, 0 warn, 0 fail, 0 skipped in 1 ms

--config-only reads tls_extra_ca_certs, so a missing CA file fails here. It doesn't read the [license] file; the full doctor reads it and verifies its signature, and so does startup.

The full doctor probes the network as the server would, through the same proxy, so run it inside the running container, which has the server's proxy variables: docker exec sentinel /usr/local/bin/altcha-sentinel doctor. Its network.host check runs once per origin of every remote file the configuration and the enabled threat sources use, plus IP lookup APIs, and license.server checks the license server when no license file is set. With the checklist above, there's nothing to probe:

license
  skip  license.server         Offline licence file configured; the licence server is not used
…
system
  skip  system.clock           No clock reference was reachable.

system.clock compares the host clock with the Date headers of those probes, so it has no reference either; keep the host on an internal NTP source. With mirrors, each mirror origin appears as a network.host result and should be ok. A failing probe names the stage (dns, tcp, or http) and the proxy in use, for example with doctor --json:

{
  "id": "network.host",
  "subject": "https://directory.altcha.org",
  "status": "fail",
  "message": "HTTP request to https://directory.altcha.org failed: error sending request for url (https://directory.altcha.org).",
  "hint": "TLS or HTTP failed: check proxies, TLS interception and the CA bundle.",
  "details": { "stage": "http", "httpStatus": null, "proxy": "http://proxy.corp.example:3128", "usedBy": ["disposable-email-domains", "free-email-domains", …] }
}

A running server lists every remote file and its last error in GET /v2/remote-files and under Remote Files. See Doctor & troubleshooting.

Start typing to search...

↑ ↓ Navigate ↵ Select