From 23739a701f85e255b420a1e594d7acb250163098 Mon Sep 17 00:00:00 2001 From: Niko Diamadis Date: Tue, 24 Dec 2024 23:31:19 -0500 Subject: [PATCH] docs: update README --- README.md | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a75e4e4..858f53d 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,34 @@ +### ⚠️ Experimental; do not use in production yet + # 🛡️ Matrix Guardian 🛡️ + [![github](https://img.shields.io/github/release/cyb3rko/matrix-guardian.svg?logo=github)](https://github.com/cyb3rko/matrix-guardian/releases/latest) [![last commit](https://img.shields.io/github/last-commit/cyb3rko/matrix-guardian?color=FE5196&logo=git&logoColor=white)](https://github.com/cyb3rko/matrix-guardian/commits/main) [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org) [![license](https://img.shields.io/github/license/cyb3rko/matrix-guardian?color=1BCC1B&logo=apache)](https://www.mozilla.org/en-US/MPL/2.0/) +- [Disclaimer](#disclaimer) - [Features](#features) - [URL Filter 🌐](#url-filter-) - [URL Phishing Check 🗡️](#url-phishing-check-) - [VirusTotal](#virustotal) - [FishFish](#fishfish) - [File MIME Type Filter 📎](#file-mime-type-filter-) - - [planned] *File Virus Scan* 🦠 + - [File Virus Scan 🦠](#file-virus-scan-) + - [VirusTotal](#virustotal-1) - [planned] *Keyword Filter* 📄 - [Protected Public Rooms (Mentions)](#protected-public-rooms-mentions) - [License](#license) --- +## Disclaimer + +Guardian is not a user moderation bot and only analyzes messages themselves. +If you are looking for user moderation, check out [the-draupnir-project/Draupnir](https://github.com/the-draupnir-project/Draupnir) or [matrix-org/mjolnir](https://github.com/matrix-org/mjolnir). + +--- + ## Features ### URL Filter 🌐 @@ -64,6 +76,21 @@ Guardian supports file MIME type filtering based on a customizable MIME type lis - `!gd mime unblock application/zip` - `!gd mime list` +### File Virus Scan 🦠 + +Guardian supports checking message attachments for malware. +(Currently this is limited to hash-based lookup, the long delay of live scans is a problem). +The analysis can be powered by the following providers: + +#### VirusTotal + +**Reference**: https://docs.virustotal.com/reference/file-info +**API-Key (required)**: `GUARDIAN_VIRUS_TOTAL_KEY: ` +**Activation (default: false)**: `GUARDIAN_VIRUS_CHECK_VIRUS_TOTAL: true|false` + +VirusTotal allows passing a hash (Guardian uses sha256) and returning a related report if one exists. +Guardian rates a URL "suspicious" if the statistic `malicious` is >1 or `suspicious` is >3. + ## Protected Public Rooms (Mentions) This list showcases some of the rooms who use the Matrix Guardian 🛡️: