Architecture and request pipeline

CLI man page: safesquid(7)

SafeSquid sits between client browsers and the Internet (or upstream proxies). Each connection is handled by a worker that processes one HTTP transaction at a time, or a CONNECT tunnel for HTTPS.

Setting up for the first time? Follow First configuration. This page explains how the pieces fit together.

Two configuration layers

Web UI (policy) — Access restrictions, Access Profiles, filters, scanners, and so on. Stored as sections in config.xml. This is what most administrators edit daily.
startup.ini (process) — Listen fallback, threads, log levels, TLS and sync tunables. Edited on the appliance filesystem — see startup.ini.

What to configure first

This is setup order, not the order a live request is processed.

Network settings — where SafeSquid listens
Access restrictions — who may connect, login if required, HTTP vs HTTPS rights
Access Profiles — which sites and content to allow
Everything else — HTTPS Inspection, scanners, cookie/header filters, Caching

What happens to a request

Names below are the Web UI section titles, in the order SafeSquid calls them. A request is either HTTPS or HTTP, never both in sequence. Access Profiles Deny is remembered early and only enforced later. DLP, Clam antivirus, and SqScan are queued as their own steps (upload, then downloaded body). Chart B is drawn from this procedure.

When a browser uses the proxy:

Network settings
  already listening on the port the browser uses

System configuration
  timeouts, buffers, CONNECT port range (used later)

Read the request
  which site, which page, HTTP or HTTPS
  (not a Web UI section)

If the destination is unsafe or internal:
  Templates → block page
  STOP

If the Host is the Web UI (safesquid.cfg):
  skip Time Profiler, Application Signatures, Request Types,
      Categorize Web-Sites, SSqore, and Access Profiles
  Access restrictions
    who may open the console; login if required
    refuse or login challenge → STOP
  show the Web UI
  STOP
  (Access Profiles Deny cannot lock you out of the console)

Otherwise this is a normal visit:

Time Profiler
Application Signatures
Request Types
Categorize Web-Sites
SSqore
  SSqore runs only if the site is still uncategorized
  these attach labels; they do not block

Access Profiles
  remember Allow or Deny
  do not block yet

Access restrictions
  Integrate LDAP is consulted here if you configured it
  External applications may assist login
  must log in → prompt, STOP until they succeed
  not allowed → Templates, STOP
  remember HTTP, HTTPS, Bypass rights and User-Groups

Access Profiles
  run again (User-Groups from Access can change the match)

Speed Limits
  can delay or block
  System configuration may hold a large upload

Content modifier
External applications
ICAP
HTTPS Inspection
Subscription
  request-modify stage; any of these can finish the request locally

HTTPS or HTTP — not both:

  HTTPS:
    Access restrictions — CONNECT right, else Templates STOP
    System configuration — CONNECT port range, else STOP
    HTTPS Inspection — if it decrypts: start again at Read the request
    else continue as a tunnel

  HTTP:
    Access restrictions — HTTP / proxy / transparent rights, else STOP
    Redirect — first match → 302, STOP

Access Profiles
  now enforce Deny (unless temporary bypass) → Templates STOP
  HTTPS Inspection can also block here

If the request has an upload body:
  Application Signatures
  Request Types
  Access Profiles
  Clam antivirus
  SqScan
  Image analyzer
  DLP
    first of these that denies → Templates STOP
    DLP inspects this upload only, not the page that comes back

Caching

DNS Blacklist
  matching block policy → Templates STOP

Proxy chain
  upstream proxy or go direct

Header filter
Cookie filter
Elevated Privacy
Content modifier
  on headers sent to the origin

Fetch the response (cache hit or the Internet)

Response Types
Access Profiles
  MIME / response labels; Deny → Templates STOP

SqScan
Clam antivirus
Image analyzer
Text analyzer
ICAP
  these inspect the downloaded body (malware and content)
  match → Templates STOP
  DLP does not run here

Prefetching
  linked objects in HTML
FTP browsing
  ftp:// only
Templates if a block page is needed
send the page to the browser
write logs

Open a section: Network settings · System configuration · Templates · Time Profiler · Application Signatures · Request Types · Categorize Web-Sites · SSqore · Access Profiles · Access restrictions · Integrate LDAP · External applications · Speed Limits · Content modifier · ICAP · HTTPS Inspection · Subscription · Redirect · DLP · Caching · DNS Blacklist · Proxy chain · Header filter · Cookie filter · Elevated Privacy · Response Types · Clam antivirus · SqScan · Image analyzer · Text analyzer · Prefetching · FTP browsing

Request pipeline using Web UI section names — Chart B — same procedure, Web UI section names in call order. Yes goes right and stops. No continues down. HTTPS and HTTP are a fork, then they meet again.

Open the Web UI at http://safesquid.cfg/ from a machine that Access restrictions allows. That path skips Access Profiles so you can still fix a mistaken Deny. HTTPS Inspection does not continue this HTTPS request — it decrypts and runs the inner HTTP from Read the request again. DLP inspects upload bodies only. Clam antivirus and SqScan inspect uploads and downloaded bodies. Direct (unbuffered) downloads skip the downloaded-body scanners.

Example — one blocked HTTPS visit

A user on the LAN opens https://social.example/ through the proxy:

Network settings, Read the request, and the host check pass (public site).
Not the Web UI. Time Profiler, Application Signatures, Request Types, then Categorize Web-Sites / SSqore: category may be Social.
Access Profiles remembers Deny for Social — no block page yet.
Access restrictions already allows this person; they have the HTTPS right.
The HTTPS branch only (not Redirect). Permission and System configuration CONNECT ports pass. Inspection off: stay on the tunnel.
Access Profiles now enforces Deny: Templates block page. Detailed logs show which rule fired.

Example — DLP on upload, malware on download

A user POSTs a spreadsheet. After Access Profiles Allow, the upload body is inspected: Clam antivirus, SqScan, Image analyzer, then DLP. A DLP MIME policy match sends Templates and stops — Caching and the origin never see that body.
A later GET of an executable is Allowed by Access Profiles. Caching misses, DNS Blacklist passes, Proxy chain fetches it. SqScan or Clam antivirus on the downloaded body match: Templates block page. DLP does not run on that download.

Policy matching styles

Dual allow/deny lists — Access restrictions, Cookie filter, Header filter. List order depends on the section default policy.
First match — Clam antivirus, HTTPS Inspection, Redirect, DNS Blacklist block policies, and several scanners.
All matches — Access Profiles (secondary), Speed Limits, Content modifier, Application Signatures.
Last match — DLP MIME policies (OCR uses cumulative score vs Threshold).
Groups — Menu groups (Accelerators, Real time content security) contain child sections only; they have no policy lists of their own.

Bypass

Access restrictions entries can grant Bypass for Header filter, Cookie filter, Redirect, Content modifier, Proxy chain, Text analyzer, DNS Blacklist, antivirus, ICAP, and DLP. That skips those modules for matching clients. Separate from Access Profiles temporary bypass cookies (Allow bypassing).

Debug headers

When System configuration → Send Debugging Headers To is CLIENT, SERVER, or BOTH, SafeSquid adds identity and policy headers. Prefer CLIENT only on a test network. See Debug response headers.

Start here

Infrastructure and access

Policies and profiles

Filtering and privacy

Performance

Security scanners

Two configuration layers

What to configure first

What happens to a request

Example — one blocked HTTPS visit

Example — DLP on upload, malware on download

Policy matching styles

Bypass

Debug headers

See also

​Two configuration layers

​What to configure first

​What happens to a request

​Example — one blocked HTTPS visit

​Example — DLP on upload, malware on download

​Policy matching styles

​Bypass

​Debug headers

​See also

Two configuration layers

What to configure first

What happens to a request

Example — one blocked HTTPS visit

Example — DLP on upload, malware on download

Policy matching styles

Bypass

Debug headers

See also