noteguard

the nostr relay spam guardian
git clone git://jb55.com/noteguard
Log | Files | Refs | README | LICENSE

README.md (4310B)

      1 
      2 # noteguard
      3 
      4 A high performance note filter plugin system for [strfry]
      5 
      6 ## Usage
      7 
      8 Filters are registered and loaded from the [noteguard.toml](noteguard.toml) config.
      9 
     10 You can add any new filter you want by implementing the `NoteFilter` trait and registering it with noteguard via the `register_filter` method.
     11 
     12 The `pipeline` config specifies the order in which filters are run. When the first `reject` or `shadowReject` action is hit, then the pipeline stops and returns the rejection error.
     13 
     14 ```toml
     15 pipeline = ["protected_events", "kinds", "whitelist", "ratelimit", "forwarder"]
     16 
     17 [filters.ratelimit]
     18 posts_per_minute = 8
     19 whitelist = ["127.0.0.1"]
     20 
     21 [filters.whitelist]
     22 pubkeys = ["16c21558762108afc34e4ff19e4ed51d9a48f79e0c34531efc423d21ab435e93"]
     23 ips = ["127.0.0.1"]
     24 
     25 [filters.kinds]
     26 kinds = [30065, 1064]
     27 
     28 [filters.kinds.messages]
     29 30065 = "blocked: files on nostr is dumb"
     30 1064 = "blocked: files on nostr is dumb"
     31 
     32 [filters.protected_events]
     33 
     34 [filters.forwarder]
     35 relay = "ws://localhost:8080"
     36 queue_size = 2000
     37 ```
     38 
     39 ## Installation
     40 
     41 You can install noteguard by copying the binary to the strfry directory.
     42 
     43 Static musl builds are convenient ways to package noteguard for deployment. It enables you to copy the binary directly to your server, ensure that you are using the correct architecture that your server is running.
     44 
     45 You most likely want `x86_64-unknown-linux-musl` or `aarch64-unknown-linux-musl`. Install this target with rustup, build noteguard, and copy the binary to the server:
     46 
     47 ```sh
     48 $ rustup target add x86_64-unknown-linux-musl
     49 $ cargo build --target x86_64-unknown-linux-musl --release
     50 $ scp ./target/x86_64-unknown-linux-musl/release/noteguard server:strfry
     51 $ scp noteguard.toml server:strfry
     52 ```
     53 
     54 Test that the binary executes by running it on the server:
     55 
     56 ```sh
     57 $ cd strfry
     58 $ <<<'{}' ./noteguard
     59 Failed to parse input: missing field `type` at line 1 column 2
     60 ```
     61 
     62 Configure `noteguard.toml` with your preferred filters.
     63 
     64 Now you can then setup your `strfry.conf` to use the noteguard by adding it as a writePolicy plugin:
     65 
     66 ```
     67 writePolicy {
     68     # If non-empty, path to an executable script that implements the writePolicy plugin logic
     69     plugin = "./noteguard"
     70 }
     71 ```
     72 
     73 And you're done! Enjoy.
     74 
     75 ## Filters
     76 
     77 You can use any of the builtin filters, or create your own!
     78 
     79 This is the initial release, and only includes one filter so far:
     80 
     81 ### Ratelimit
     82 
     83 * name: `ratelimit`
     84 
     85 The ratelimit filter limits the rate at which notes are written to the relay per-ip.
     86 
     87 Settings:
     88 
     89 - `notes_per_minute`: the number of notes per minute which are allowed to be written per ip.
     90 
     91 - `whitelist` *optional*: a list of IP4 or IP6 addresses that are allowed to bypass the ratelimit.
     92 
     93 ### Whitelist
     94 
     95 * name: `whitelist`
     96 
     97 The whitelist filter only allows notes to pass if it matches a particular pubkey or source ip:
     98 
     99 - `pubkeys` *optional*: a list of hex public keys to let through
    100 
    101 - `ips` *optional*: a list of ip addresses to let through
    102 
    103 Either criteria can match
    104 
    105 ### Kinds
    106 
    107 * name: `kinds`
    108 
    109 A filter that blacklists certain kinds
    110 
    111 - `kinds`: a list of kind integers to block
    112 
    113 - `kinds.messages` *optional*: a map of kinds to message to deliver when the kind is blocked
    114 
    115 Example:
    116 
    117 ```toml
    118 [filters.kinds]
    119 kinds = [30065, 1064]
    120 
    121 [filters.kinds.messages]
    122 30065 = "blocked: files on nostr is dumb"
    123 1064 = "blocked: files on nostr is dumb"
    124 ```
    125 
    126 ### Protected Events
    127 
    128 See [nip70]
    129 
    130 * name: `protected_events`
    131 
    132 There are no config options, but an empty config entry is still needed:
    133 
    134 `[filters.protected_events]`
    135 
    136 ### Forwarder
    137 
    138 * name: `forwarder`
    139 
    140 You need to compile with the `forwarder` feature to enable this filter:
    141 
    142 ```sh
    143 $ cargo build --features forwarder --release
    144 ```
    145 
    146 The forwarder filter allows you to forward notes to another relay. Notes will
    147 be queued if the connection goes down (up to the `queue_size` buffer limit)
    148 
    149 - `relay` - the relay to forward notes to, eg: `ws://localhost:8080`
    150 
    151 - `queue_size` *optional* - size of the note queue, this is used to buffer notes if the connection goes down. Default is 1000.
    152 
    153 
    154 ## Testing
    155 
    156 You can test your filters like so:
    157 
    158 ```sh
    159 $ cargo build
    160 $ <test/inputs ./target/debug/noteguard
    161 $ ./test/delay | ./target/debug/noteguard
    162 ```
    163 
    164 [strfry]: https://github.com/hoytech/strfry
    165 [nip70]: https://github.com/nostr-protocol/nips/blob/protected-events-tag/70.md