Initial commit

README.md

@@ -1,3 +1,223 @@
-# mikrotik-adlist-builder
+# Mikrotik Adlist Builder
 
-Tool for building mikrotik adlists for blocking ands and harmful domains.
+`mikrotik-adlist-builder` is a small Python tool for building MikroTik adlists used to block ads and harmful domains.
+
+It can download multiple blocklists from remote URLs, read local files, extract valid domain names from different formats, merge them, remove duplicates, and write the final output in a MikroTik-friendly format:
+
+```text
+0.0.0.0 example.com
+0.0.0.0 ads.example.net
+```
+
+## Features
+
+- Supports multiple input sources
+- Downloads blocklists from `http://` and `https://` URLs
+- Reads local files from:
+  - relative paths such as `./custom-domains.txt`
+  - absolute paths
+  - `file://` URLs
+- Supports multiple common blocklist formats:
+  - ABP-style rules such as `||example.com^`
+  - hosts file syntax such as `0.0.0.0 example.com`
+  - plain domain lists such as `example.com`
+- Removes duplicates automatically
+- Filters out invalid entries
+- Writes a merged output file ready for MikroTik adlist import
+
+## Requirements
+
+- Python 3.9 or newer
+
+## Installation
+
+No external dependencies are required.
+
+Clone the repository or just save the script locally:
+
+```bash
+chmod +x mikrotik-adlist-builder.py
+```
+
+You can then run it directly:
+
+```bash
+./mikrotik-adlist-builder.py
+```
+
+Or with Python:
+
+```bash
+python3 mikrotik-adlist-builder.py
+```
+
+## Default sources
+
+The script includes a built-in `DEFAULT_URLS` list. Example:
+
+```python
+DEFAULT_URLS = [
+    "https://big.oisd.nl/",
+    "https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts",
+    "./custom-domains.txt",
+]
+```
+
+This means the tool can combine public online blocklists with your own local domain list.
+
+## Usage
+
+### Use default sources
+
+```bash
+python3 mikrotik-adlist-builder.py
+```
+
+This will create:
+
+```text
+adlist.txt
+```
+
+### Specify custom URLs
+
+```bash
+python3 mikrotik-adlist-builder.py \
+  -u https://big.oisd.nl/ \
+  -u https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
+```
+
+### Mix remote and local sources
+
+```bash
+python3 mikrotik-adlist-builder.py \
+  -u https://big.oisd.nl/ \
+  -u ./custom-domains.txt \
+  -u ./my-extra-list.txt
+```
+
+### Use a local file via `file://`
+
+```bash
+python3 mikrotik-adlist-builder.py \
+  -u file:///home/user/blocklists/custom.txt
+```
+
+### Change output file
+
+```bash
+python3 mikrotik-adlist-builder.py \
+  -o mikrotik-adlist.txt
+```
+
+### Full example
+
+```bash
+python3 mikrotik-adlist-builder.py \
+  -u https://big.oisd.nl/ \
+  -u https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts \
+  -u ./custom-domains.txt \
+  -o mikrotik-adlist.txt
+```
+
+## Supported input formats
+
+### 1. ABP syntax
+
+Example:
+
+```text
+||example.com^
+||ads.example.net^
+```
+
+Some simplified variants are also accepted, for example:
+
+```text
+||example.com
+```
+
+### 2. Hosts syntax
+
+Example:
+
+```text
+0.0.0.0 example.com
+127.0.0.1 ads.example.net
+```
+
+### 3. Plain domain syntax
+
+Example:
+
+```text
+example.com
+ads.example.net
+tracker.example.org
+```
+
+## Local custom domain file example
+
+Example `custom-domains.txt`:
+
+```text
+example-bad-site.com
+ads.example.net
+tracker.example.org
+```
+
+You can also mix in hosts-style entries:
+
+```text
+0.0.0.0 bad.example.com
+127.0.0.1 ads.badsite.net
+```
+
+And ABP-style rules:
+
+```text
+||tracker.example.org^
+||ads.example.net^
+```
+
+## Output format
+
+The generated file contains one domain per line in this format:
+
+```text
+0.0.0.0 domain.tld
+```
+
+Example:
+
+```text
+0.0.0.0 ads.example.com
+0.0.0.0 tracker.example.net
+0.0.0.0 malware.example.org
+```
+
+## Import into MikroTik
+
+The resulting file is intended to be used as a source for a MikroTik adlist or for further processing before import, depending on your RouterOS version and setup.
+
+## Notes
+
+- Relative local paths are resolved against the current working directory from which you run the script.
+- `file://` paths should normally be absolute.
+- Duplicate domains are removed automatically.
+- Invalid lines, comments, whitelist rules, localhost-style entries, IPv6 entries, and malformed domains are ignored.
+
+## Example output messages
+
+```text
+[INFO] Downloading: https://big.oisd.nl/
+[INFO] Domains found: 123456
+[INFO] Downloading: ./custom-domains.txt
+[INFO] Domains found: 25
+[OK] Output written to: adlist.txt
+[OK] Total unique domains: 123470
+```
+
+## License
+
+Use, modify, and distribute freely as needed.