Skip to content

Phishing attack identification tool - Performs email risk evaluations relying on different black lists, machine learning techniques, and OSINT third party services, without depending on user knowledge or awareness

License

Notifications You must be signed in to change notification settings

eliasgranderubio/cartuxeira

Repository files navigation

Cartuxeira

Python License

Cartuxeira is a tool to perform an email risk evaluation relying on both offline and online black lists, machine learning techniques such as DGA detection or EGA detection, and using OSINT third party services.

This kind of email risk evaluation provides a confident way to identify a phishing attack without depending on user knowledge or awareness.

Requirements

Before Cartuxeira usage, you must have installed the next requirements:

  • Python 3.10.X or later
  • MongoDB 6.0 or later
  • Pip3
    • PyMongo
    • Flask
    • Waitress
    • Dgad
    • TensorFlow
    • Joblib
    • PyDNSBL
    • EmailRep

The requirements can be installed with pip:

    sudo pip3 install -r requirements.txt

Installation of MongoDB

You must have installed MongoDB 6.0 or later for using Cartuxeira. MongoDB stores local black lists for both domains and emails and other relevant information.

If you need instructions for MongoDB installation, see the How-to install MongoDB Community Edition page.

You can also run MongoDB using docker:

    docker pull mongo
    docker run -d -p 27017:27017 mongo

Usage

You must run python3 cartuxeira.py for starting the Cartuxeira server. Type python3 cartuxeira.py -h for details about initial settings.

Once the server is up and running you can consume its REST API. The available API is shown below.

Local Black List Service

Cartuxeira allows to manage a local black list for both domains and emails. For each one, you can add, remove or check if it is included or not in the black list.

The domain black list specification is shown below:

DESCRIPTION Allows to add, delete or check if a domain exists in
the local black list.
METHODS POST, GET, DELETE
URL bl/domain/<string:domain>
PARAMETERS None
RETURNS HTTP/1.1 204 No Content

The email black list specification is shown below:

DESCRIPTION Allows to add, delete or check if an email exists in
the local black list.
METHODS POST, GET, DELETE
URL bl/email/<string:email>
PARAMETERS None
RETURNS HTTP/1.1 204 No Content

Email Risk Evaluation Service

This is the most important service of Cartuxeira. The email risk evaluation is relying on different black lists, machine learning techniques and third party services

The email risk evaluation specification is shown below:

DESCRIPTION Evaluates the email risk relying on offline and online
black lists, machine learning and third party services.
METHODS GET
URL risk/email/<string:email>
PARAMETERS None
RETURNS HTTP/1.1 200 OK
{
  "risk_score": "Low",
  "domain": {
    "is_dga": false,
    "is_in_offline_blacklist": false,
    "is_in_online_blacklist": false
  },
  "email": {
    "is_ega": false,
    "is_in_offline_blacklist": false,
    "reputation": {
        "details": {
            "accept_all": false,
            "blacklisted": false,
            "credentials_leaked": true,
            "credentials_leaked_recent": false,
            "data_breach": true,
            "days_since_domain_creation": 11587,
            "deliverable": false,
            "disposable": false,
            "dmarc_enforced": true,
            "domain_exists": true,
            "domain_reputation": "high",
            "first_seen": "07/01/2008",
            "free_provider": false,
            "last_seen": "05/21/2022",
            "malicious_activity": false,
            "malicious_activity_recent": false,
            "new_domain": false,
            "primary_mx": "mx.example.org",
            "profiles": ["twitter"],
            "spam": false,
            "spf_strict": true,
            "spoofable": false,
            "suspicious_tld": false,
            "valid_mx": true
        },
        "references": 101,
        "reputation": "high",
        "summary": "Not suspicious.",
        "suspicious": false
      }
  }
}

Other REST API details

Version Prefix

All API routes are prefixed with /v1/.

Backwards compatibility: At the current version, Cartuxeira does not yet promise backwards compatibility even with the v1 prefix.

HTTP Status Codes

The following HTTP status codes are used throughout the API.

  • 200 - Success with data.
  • 204 - Success, no data returned.
  • 400 - Invalid request, missing or invalid data.
  • 404 - Invalid path or requested resource not found.
  • 409 - Invalid request which generates a conflict with the current state of the target resource.
  • 500 - Internal server error. An internal error has occurred, try again later. If the error persists, report a bug.
  • 503 - Some Cartuxeira service is down. Review Cartuxeira logs.

Bonus Track: Quick Start with Docker Compose

This section describes the installation of Cartuxeira using docker-compose, including the Mongo database and the Cartuxeira server.

Execute the following commands in the root folder of Cartuxeira and then, the Cartuxeira server will start listening at port 5000:

    docker-compose build
    docker-compose up -d

Bugs and Feedback

For bugs, questions and discussions please use the Github Issues or ping us on Twitter (@3grander or @DLTorreLand).

About

Phishing attack identification tool - Performs email risk evaluations relying on different black lists, machine learning techniques, and OSINT third party services, without depending on user knowledge or awareness

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages