Configuration

Every setting has a default, so Aliens Eye needs no configuration. To change the defaults for every scan, put them in a JSON file; command-line options still win.

Diagram: Diagram — Click to open at full size

#Where the file is read from

The first of these that exists:

the file given with --config PATH;
config.json in the current directory;
config.json in the user configuration directory:

System	Directory
Linux	`~/.config/aliens_eye/`
macOS	`~/Library/Application Support/aliens_eye/`
Windows	`%LOCALAPPDATA%\aliens_eye\aliens_eye\`

The same directory holds a sites.d/ folder for your own sites.

#Example

json

{
  "concurrent": 50,
  "timeout": 10.0,
  "retries": 2,
  "rate_limit_delay": 0.2,
  "output_dir": "results",
  "output_formats": ["json", "html"],
  "catalog": "extended",
  "exclude_nsfw": true,
  "level": "basic"
}

#Settings

#Network

Setting	Default	Command line	Means
`concurrent`	`50`	`-c`	Requests in flight at once.
`timeout`	`10.0`	`--timeout`	Seconds to wait for one response.
`retries`	`2`	`--retries`	Retries for a failed request (timeouts, 408, 429, 500, 502, 503, 504).
`backoff_base`	`0.5`	`--backoff-base`	First wait before a retry, in seconds; doubles each time.
`backoff_cap`	`8.0`	`--backoff-cap`	Longest wait between retries.
`jitter`	`0.2`		Random spread added to each wait.
`rate_limit_delay`	`0.2`	`--rate-limit`	Minimum seconds between two requests to the same site.
`max_content_bytes`	`100000`	`--max-bytes`	Most of a page that is read and parsed.
`proxy`	none	`--proxy`, `--tor`	`http://`, `https://`, `socks4://` or `socks5://` proxy.

A Retry-After header from the site is respected up to backoff_cap. A site asking for a longer wait gets no retry, so one site cannot hold up the whole scan.

#Detection

Setting	Default	Command line	Means
`use_ml`	`true`	`--no-ml`	Blend the ML model with the heuristics; `false` uses heuristics alone.
`control_check`	`true`	`--no-control-check`	Check every Found against a made-up username; see How it works.
`use_playwright`	`false`	`--playwright`	Render Maybe pages in a browser and look again. Needs the `browser` extra.
`fingerprints_path`	platform cache		Where page fingerprints are kept between scans.
`max_fingerprints_per_label`	`50`		Fingerprints kept per site for each of Found and Not Found.

A custom model is given with --model model.json; see Training the model.

#Sites

Setting	Default	Command line	Means
`catalog`	`"extended"`	`--catalog`	`extended` (7,700+ sites) or `standard` (788).
`exclude_nsfw`	`false`	`--no-nsfw`	Skip adult sites.
`include_tags`	none	`--tag`	Only sites with these tags, as a list.
`include_sources`	none	`--source`	Only entries from these sources (`maigret`, `sherlock`).

#Output

Setting	Default	Command line	Means
`output_dir`	`"results"`	`--output`	Where reports are written.
`output_formats`	`["json"]`	`--format`	Report formats; see Reports.
`level`	`"basic"`	`-l`	Default scan level when none is given.
`explain`	`false`	`--explain`	Show the evidence behind each verdict.

#Environment variables

Variable	Effect
`ALIENS_EYE_NO_PROMO=1`	Hides the note about the author's other project under the banner.

#Files Aliens Eye keeps

What	Where
Reports	`results/` in the directory you scan from, or `output_dir`
Page fingerprints	the platform cache directory, e.g. `~/.cache/aliens_eye/fingerprints.json`
Library scans' scratch reports	the same cache directory, under `api/`