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:
| Host | Used by | When | Turn off or redirect with |
|---|---|---|---|
directory.altcha.org | The six classifier lists, [eml.malicious_hashes], [web_bot_auth], and the 15 threat sources seeded on first boot | In the background at startup, then on each list's schedule | enabled = false or url per list; [threats] seed_defaults; each threat source's url |
altcha.org | The 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.org | The 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:
| Host | Used by | Air-gapped alternative |
|---|---|---|
license.altcha.org | [license] key (online activation and daily refresh) | [license] file; see License |
download.maxmind.com, ipinfo.io | maxmind and ipinfo-mmdb IP resolver providers with a url | A local .mmdb with path |
ip-api.com, pro.ip-api.com, api.ipstack.com, api.ipinfo.io, ipinfo.io | ip-api, ipstack, and ipinfo IP resolver providers | Remove 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.com | Web push of alerts ([alerts.push]), to the push services in users' subscriptions | Leave [alerts.push] subject unset; use webhooks or email |
| Your own hosts | The 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:
| Variable | Applies to |
|---|---|
HTTPS_PROXY | Requests to https:// URLs |
HTTP_PROXY | Requests to http:// URLs |
ALL_PROXY | Both, when the scheme has no variable of its own |
NO_PROXY | Comma-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.1The 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, andsslrootcertorssl-cain[database] url, replace both the system store andtls_extra_ca_certsfor 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=1Mirror 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.gznames unchanged. A URL whose path ends in.csv.gzis read in the directory's format (header line dropped) on any host. Sentinel keeps the.csvfile from the gzip, so a gzip you create yourself must store a name ending in.csv, or no name at all (gzip -n). - Serve
ETagorLast-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.orgisn'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 withPATCH /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 = falseThen check the rest of your configuration:
- Don't configure internet-hosted providers: no IP lookup APIs,
.mmdbfiles bypathinstead ofurl,[similarity.local] model_pathandtokenizer_pathinstead 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, theagentcondition never matches. Without threat sources, only manual and automatic threat entries match thethreatcondition. - 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(default1h), and timeouts or SERVFAIL for 30 seconds at most, so a resolver that drops queries costs each domain onedns_timeoutper 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-onlyaltcha-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.