# logactio

logactio is a lightweight daemon that watches log files for lines matching
configured regular expressions and triggers configurable actions when they do.
It is intended for situations where you want to react automatically to log
events — sending an alert mail, posting to a web endpoint, or blocking an IP
address — without writing custom scripts.

Each watched log file runs in its own thread and uses inotify for instant,
low-overhead detection of new log lines.  Log rotation is handled
automatically.

## Concepts

- **Logfile** — a log file to watch, with an optional default set of reporters.
- **Rule** — a regular expression matched against each new log line.  Rules
  reference a logfile and define a threshold (how many hits before triggering)
  and optional time-frame and rate-limit controls.
- **Reporter** — the action taken when a rule fires.  Built-in reporters:
  - **Default** — writes the event to the logactio log.
  - **HTTPreporter** — HTTP/HTTPS GET or POST (plain or JSON body).
  - **SMTPreporter** — sends an e-mail via SMTP, with optional SSL/STARTTLS.
  - **IPTipset** — adds an extracted IP address to an ipset list (iptables).
  - **NftablesSet** — adds an extracted IP address to a pre-existing nftables
    set.  Supports native nft set timeouts for automatic expiry.

## Installation

Requires Python 3.6+ and `inotify_simple`.

```sh
$ pip install .
```

For system-wide installation:

```sh
$ sudo pip install .
```

The default configuration file location is `/etc/logactio.cfg`.

## Running

```sh
# Run in the foreground (useful for testing):
$ logactio -L stdout -v

# Run as a daemon:
$ logactio -d --pid-file /run/logactio.pid

# Use a non-default config file:
$ logactio -c /path/to/my.cfg -d
```

Run `logactio --help` for a full list of options.

## Configuration

See the full documentation for detailed configuration reference.  A minimal
example:

```ini
[Reporter:mail]
module: SMTPreporter
sender: logactio@example.com
recipients: admin@example.com
smtp_host: localhost

[Logfile:auth]
file: /var/log/auth.log
reporters: mail

[Rule:ssh-fail]
logfile: auth
regex: Failed password for .* from (\S+)
threshold: 5
time-frame: 60
```

This watches `/var/log/auth.log` and sends a mail after 5 failed SSH login
attempts from the same IP within 60 seconds.

## Building the documentation

The documentation is built with [Sphinx](https://www.sphinx-doc.org/).

```sh
$ cd docs
$ make html
```

The generated HTML will be in `docs/build/html/`.  Other output formats
(`make latexpdf`, `make man`, etc.) are also available — run `make help`
inside the `docs/` directory for a full list.


## Source code repository

This project uses Radicle Network as the main project hosting.  Mirrors
on centralised git forges may be used additionally, but all patches and
issue tracking is expected to use the Radicle tools.

See the [Radicle Quick-start guide](https://radicle.dev/guides/quick-start)
for details how to install and get ready to use Radicle.  Once installed,
run the following command to clone this project:

```sh
$ rad clone rad:z3L9dYEExJhof9DvqvgsMF88ZMySi
```

### Source code mirrors:
- fedorapeople.org: https://fedorapeople.org/cgit/dsommers/public_git/logactio.git/
- Codeberg.org: https://codeberg.org/dazo/logactio
