samoth69/sentimail

L'expert de la détection de mail malveillant

SentiMail

The expert in malicious email detection

=> Voir le dossier docs pour avoir la documentation du projet.

build-push-check-action : https://forge.cpe.granux.fr/sentimail/build-push-check-action

📝 Table of Contents

• Features
• Tech Stack
• Getting Started
• API Documentation
• Authors

Features

SentiMail performs three types of analyses on the email:

Metadata Analysis

• Analysis of the sender's IP
• Analysis of the sender's domain
• Analysis of the sender domain's SPF

Email Content Analysis

• Link analysis
• Spelling analysis
• Keyword analysis
• Typo-squatting analysis
• Unusual characters analysis

Attachments Analysis

• Analysis of attachment hashes
• Analysis of attachment file types

For more informations about the technical specifications, please refer to the technical specifications. For more informations about the security plan, please refer to the security plan.

Tech Stack

Backend

• Django
• Django REST Framework
• RabbitMQ
• PostgreSQL
• Minio

Infrastructure

• Docker
• Kubernetes
• Traefik
• CrowdSec
• SonarQube
• Harbor

Getting Started

🛠️ Run locally

• Clone the repository
• Copy the sample.env file to .env and fill in the variables
• Run docker compose up -d --build
• Open http://localhost:8000 in your browser

API Documentation

Authentication

• Generate a new API key
• Use the API key in the header of your request:
  • Key: Authorization
  • Value: Token <API_KEY>

Submit email

POST /api/submit/

Request:

Content-Type: multipart/form-data Body:

• Key: file
• Value: <mail_file>

Response:

Code	Description
200	OK
400	Bad Request
401	Unauthorized
500	Internal Server Error

Request sample:

curl --location 'http://<ip>/api/submit/' \
--header 'Authorization: Token <API_KEY>' \
--form 'file=@"</path/mail_file>"'

Response sample (200 OK):

{
    "uuid": "1574c5a7-2860-4659-a538-6210d074fb3d"
}

Get email analysis for authenticated user

GET /api/analysis/<uuid>/

Response:

Code	Description
200	OK
400	Bad Request
401	Unauthorized
404	Not Found
500	Internal Server Error

Request sample:

curl --location 'http://<ip>/api/analysis/1574c5a7-2860-4659-a538-6210d074fb3d' \
--header 'Authorization: Token 27cdb16b2189fdc09f008fd901f54306f155697a'

Response sample (200 OK):

{
    "uuid": "1574c5a7-2860-4659-a538-6210d074fb3d",
    "created_at": "2023-12-14T10:41:45.989923Z",
    "user": "anonymous",
    "isReady": false,
    "responseMetadataIp": "IP is not malicious",
    "responseMetadataDomain": "Mail is not malicious",
    "responseMetadataSPF": "SPF record is valid"
}

Get email analysis for anonymous user

GET /api/result/<uuid>/

Response:

Code	Description
200	OK
400	Bad Request
401	Unauthorized
404	Not Found
500	Internal Server Error

Request sample:

curl --location 'http://<ip>/api/result/1574c5a7-2860-4659-a538-6210d074fb3d' \
--header 'Authorization: Token 27cdb16b2189fdc09f008fd901f54306f155697a'

Response sample (200 OK):

{
    "uuid": "1574c5a7-2860-4659-a538-6210d074fb3d",
    "created_at": "2023-12-14T10:41:45.989923Z",
    "user": "anonymous",
    "isReady": false,
    "responseMetadataIp": "IP is not malicious",
    "responseMetadataDomain": "Mail is not malicious",
    "responseMetadataSPF": "SPF record is valid"
}

Update email analysis

PATCH /api/analysis/<uuid>/

Response:

Code	Description
200	OK
400	Bad Request
401	Unauthorized
404	Not Found
500	Internal Server Error

Request sample:

curl --location --request PATCH 'http://<ip>/api/analysis/0b3cf9d0-fcb3-4bf6-9a29-33abcaab4826/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token 27cdb16b2189fdc09f008fd901f54306f155697a' \
--data '{
    "responseMetadataIp": "IP not found in database",
    "responseMetadataDomain": "Mail is not malicious",
    "responseMetadataSPF": "SPF record is invalid"
}'

Response sample (200 OK):

{
    "uuid": "0b3cf9d0-fcb3-4bf6-9a29-33abcaab4826",
    "created_at": "2023-12-14T10:41:45.989923Z",
    "user": "anonymous",
    "isReady": false,
    "responseMetadataIp": "IP not found in database",
    "responseMetadataDomain": "Mail is not malicious",
    "responseMetadataSPF": "SPF record is invalid"
}

🙇 Author

Thomas Genin

Nicola Piemontese

Valentin Tournier

Thomas Violent