|
| 1 | +# page-fetch |
| 2 | + |
| 3 | +page-fetch is a tool for researchers that lets you: |
| 4 | + |
| 5 | +* Fetch web pages using headless Chrome, storing all fetched resources including JavaScript files |
| 6 | +* Run arbitrary JavaScript on many web pages and see the returned values |
| 7 | + |
| 8 | + |
| 9 | +## Installation |
| 10 | + |
| 11 | +page-fetch is written with Go and can be installed with `go get`: |
| 12 | + |
| 13 | +``` |
| 14 | +▶ go get github.com/detectify/page-fetch |
| 15 | +``` |
| 16 | + |
| 17 | +Or you can clone the respository and build it manually: |
| 18 | + |
| 19 | +``` |
| 20 | +▶ git clone https://github.com/detectify/page-fetch.git |
| 21 | +▶ cd page-fetch |
| 22 | +▶ go install |
| 23 | +``` |
| 24 | + |
| 25 | +### Dependencies |
| 26 | + |
| 27 | +page-fetch uses [chromedp](https://github.com/chromedp/chromedp), which requires |
| 28 | +that a Chrome or Chromium browser be installed. It uses the following list of |
| 29 | +executable names in attempting to execute a browser: |
| 30 | + |
| 31 | +* `headless_shell` |
| 32 | +* `headless-shell` |
| 33 | +* `chromium` |
| 34 | +* `chromium-browser` |
| 35 | +* `google-chrome` |
| 36 | +* `google-chrome-stable` |
| 37 | +* `google-chrome-beta` |
| 38 | +* `google-chrome-unstable` |
| 39 | +* `/usr/bin/google-chrome` |
| 40 | + |
| 41 | + |
| 42 | +## Basic Usage |
| 43 | + |
| 44 | +page-fetch takes a list of URLs as its input on `stdin`. You can provide the input list using IO redirection: |
| 45 | + |
| 46 | +``` |
| 47 | +▶ page-fetch < urls.txt |
| 48 | +``` |
| 49 | + |
| 50 | +Or using the output of another command: |
| 51 | + |
| 52 | +``` |
| 53 | +▶ grep admin urls.txt | page-fetch |
| 54 | +``` |
| 55 | + |
| 56 | +By default, responses are stored in a directory called 'out', which is created if it does not exist: |
| 57 | + |
| 58 | +``` |
| 59 | +▶ echo https://detectify.com | page-fetch |
| 60 | +GET https://detectify.com/ 200 text/html; charset=utf-8 |
| 61 | +GET https://detectify.com/site/themes/detectify/css/detectify.css?v=1621498751 200 text/css |
| 62 | +GET https://detectify.com/site/themes/detectify/img/detectify_logo_black.svg 200 image/svg+xml |
| 63 | +GET https://fonts.googleapis.com/css?family=Merriweather:300i 200 text/css; charset=utf-8 |
| 64 | +... |
| 65 | +▶ tree out |
| 66 | +out |
| 67 | +├── detectify.com |
| 68 | +│ ├── index |
| 69 | +│ ├── index.meta |
| 70 | +│ └── site |
| 71 | +│ └── themes |
| 72 | +│ └── detectify |
| 73 | +│ ├── css |
| 74 | +│ │ ├── detectify.css |
| 75 | +│ │ └── detectify.css.meta |
| 76 | +... |
| 77 | +``` |
| 78 | + |
| 79 | +The directory structure used in the output directory mirrors the directory structure used on the target websites. |
| 80 | +A ".meta" file is stored for each request that contains the originally requested URL, including the query string), |
| 81 | +the request and response headers etc. |
| 82 | + |
| 83 | + |
| 84 | +## Options |
| 85 | + |
| 86 | +You can get the page-fetch help output by running `page-fetch -h`: |
| 87 | + |
| 88 | +``` |
| 89 | +▶ page-fetch -h |
| 90 | +Request URLs using headless Chrome, storing the results |
| 91 | +
|
| 92 | +Usage: |
| 93 | + page-fetch [options] < urls.txt |
| 94 | +
|
| 95 | +Options: |
| 96 | + -c, --concurrency <int> Concurrency Level (default 2) |
| 97 | + -e, --exclude <string> Do not save responses matching the provided string (can be specified multiple times) |
| 98 | + -i, --include <string> Only save requests matching the provided string (can be specified multiple times) |
| 99 | + -j, --javascript <string> JavaScript to run on each page |
| 100 | + -o, --output <string> Output directory name (default 'out') |
| 101 | + -w, --overwrite Overwrite output files when they already exist |
| 102 | + --no-third-party Do not save responses to requests on third-party domains |
| 103 | + --third-party Only save responses to requests on third-party domains |
| 104 | +``` |
| 105 | + |
| 106 | +### Concurrency |
| 107 | + |
| 108 | +You can change how many headless Chrome processes are used with the `-c` / `--concurrency` option. |
| 109 | +The default value is 2. |
| 110 | + |
| 111 | +### Excluding responses based on content-type |
| 112 | + |
| 113 | +You can choose to not save responses that match particular content types with the `-e` / `--exclude` option. |
| 114 | +Any response with a content-type that partially matches the provided value will not be stored; so you can, |
| 115 | +for example, avoid storing image files by specifying: |
| 116 | + |
| 117 | +``` |
| 118 | +▶ page-fetch --exclude image/ |
| 119 | +``` |
| 120 | + |
| 121 | +The option can be specified multiple times to exclude multiple different content-types. |
| 122 | + |
| 123 | +### Including responses based on content-type |
| 124 | + |
| 125 | +Rather than excluding specific content-types, you can opt to only save certain content-types with the |
| 126 | +`-i` / `--include` option: |
| 127 | + |
| 128 | +``` |
| 129 | +▶ page-fetch --include text/html |
| 130 | +``` |
| 131 | + |
| 132 | +The option can be specified multiple times to include multiple different content-types. |
| 133 | + |
| 134 | +### Running JavaScript on each page |
| 135 | + |
| 136 | +You can run arbitrary JavaScript on each page with the `-j` / `--javascript` option. The return value |
| 137 | +of the JavaScript is converted to a string and printed on a line prefixed with "JS": |
| 138 | + |
| 139 | +``` |
| 140 | +▶ echo https://example.com | page-fetch --javascript document.domain |
| 141 | +GET https://example.com/ 200 text/html; charset=utf-8 |
| 142 | +JS (https://example.com): example.com |
| 143 | +``` |
| 144 | + |
| 145 | +This option can be used for a very wide variety of purposes. As an example, you could extract the `href` |
| 146 | +attribute from all links on a webpage: |
| 147 | + |
| 148 | +``` |
| 149 | +▶ echo https://example.com | page-fetch --javascript '[...document.querySelectorAll("a")].map(n => n.href)' | grep ^JS |
| 150 | +JS (https://example.com): [https://www.iana.org/domains/example] |
| 151 | +``` |
| 152 | + |
| 153 | +### Setting the output directory name |
| 154 | + |
| 155 | +By default, files are stored in a directory called `out`. This can be changed with the `-o` / `--output` option: |
| 156 | + |
| 157 | +``` |
| 158 | +▶ echo https://example.com | page-fetch --output example |
| 159 | +GET https://example.com/ 200 text/html; charset=utf-8 |
| 160 | +▶ find example/ -type f |
| 161 | +example/example.com/index |
| 162 | +example/example.com/index.meta |
| 163 | +``` |
| 164 | + |
| 165 | +The directory is created if it does not already exist. |
| 166 | + |
| 167 | +### Overwriting files |
| 168 | + |
| 169 | +By default, when a file already exists, a new file is created with a numeric suffix, e.g. if `index` already exists, |
| 170 | +`index.1` will be created. This behaviour can be overridden with the `-w` / `--overwrite` option. When the option is |
| 171 | +used matching files will be overwritten instead. |
| 172 | + |
| 173 | +### Excluding third-party responses |
| 174 | + |
| 175 | +You may sometimes wish to exclude responses from third-party domains. This can be done with the `--no-third-party` option. |
| 176 | +Any responses to requests for domains that do not match the input URL, or one of its subdomains, will not be saved. |
| 177 | + |
| 178 | +### Including only third-party responses |
| 179 | + |
| 180 | +On rare occasions you may wish to *only* store responses to third party domains. This can be done with the `--third-party` option. |
0 commit comments