readme.md 2.12 KB
Newer Older
1
# Inspector
Aral Balkan's avatar
Aral Balkan committed
2

Aral Balkan's avatar
Aral Balkan committed
3
Inspector is a series of tools that helps bootstrap investigations into web malware (trackers, etc.)
Aral Balkan's avatar
Aral Balkan committed
4
5
6

## How it works

Aral Balkan's avatar
Aral Balkan committed
7
Inspector loads in a web page from a URL (or a local HAR file) and generates an [HTTP Archive (HAR file)](http://www.softwareishard.com/blog/har-12-spec/) from it and saves it in *~/better.fyi/archive/*.
Aral Balkan's avatar
Aral Balkan committed
8
9
10

It then analyses the HAR file and:

11
12
13
* Generates a draft entry for the site itself under *~/better.fyi/drafts/sites/*
* Generates a draft list of third-party content that is accessed by the site and adds them to *~/better.fyi/drafts/trackers/*
* Non-destructively updates the list of trackers in published site entries under *~/better.fyi/content/sites/*
Aral Balkan's avatar
Aral Balkan committed
14

Aral Balkan's avatar
Aral Balkan committed
15
Drafts are just that, drafts. They are meant as a convenient starting point to an investigation with space to note what we find, not as final documents.
Aral Balkan's avatar
Aral Balkan committed
16

Aral Balkan's avatar
Aral Balkan committed
17
18
19
20
21
22
**Drafts should never be checked into published content without manual review and editing.**

This point cannot be stressed enough: **the manual investigation and editing process is the heart and soul of Better.**

## Inquiry

23
Inquiry is a tool that runs inspections on [the domains currently being tracked by Better](https://source.ind.ie/better/domains).
Aral Balkan's avatar
Aral Balkan committed
24
25
26
27
28
29
30

## Installation

```bash
./install
```

31
32
33
<!-- Removing the interactive inspection option for now as it doesn’t work with puppeteer launch of Chrome -->
<!-- ./inspect <URL> -i		: interactive -->

Aral Balkan's avatar
Aral Balkan committed
34
35
36
## Usage

```bash
Aral Balkan's avatar
Aral Balkan committed
37
38
39
40
41
./inspect <URL>			: non-interactive
./inspect -f <path>		: analyse HTTP Archive file (.har/.har.gz) at path

./inquiry				: start an inquiry
./inquiry --local		: re-examine the existing HTTP Archives in the archive
Aral Balkan's avatar
Aral Balkan committed
42
43
```

Aral Balkan's avatar
Aral Balkan committed
44
45
46
47
## Known issues

[44](https://source.ind.ie/better/inspector/issues/44): In order to work around Chromium crashes crashing the inquiry, we are now running a fresh Chromium instance for each inspection (to workaround [issue 43](https://source.ind.ie/better/inspector/issues/43)). This currently has the side-effect that you cannot easily exit an inquiry. The easiest way at the moment is to close the terminal tab (and check the processing for a dangling Chromium instance to kill.)

Aral Balkan's avatar
Aral Balkan committed
48
49
## License

Aral Balkan's avatar
Aral Balkan committed
50
Inspector is released under GNU AGPLv3.