django-attack-blocker 1.0.0

ML-based IP blocking system for Django

Django Attack Blocker

A machine learning-based IP blocking library for Django applications to detect and prevent malicious network traffic.

Overview

Django Attack Blocker is a demonstration library that shows how trained models on the UNSW dataset can be used to protect specific routes in Django applications. The library uses machine learning to identify potentially malicious network traffic and can automatically block IP addresses based on the model's predictions.

This middleware integrates seamlessly with Django applications and can be used to protect sensitive routes from various network attacks such as DoS, DDoS, reconnaissance, and exploitation attempts.

Features

• Machine learning-based detection of malicious network traffic
• IP address blocking and whitelisting capabilities
• Configurable blocking thresholds
• Temporary and permanent IP blocks
• Django view decorators for easy integration
• Built-in caching of block decisions for performance
• Support for trusted IP ranges
• Detailed statistics tracking

Installation

pip install django_attack_blocker

Required Files

The required model and encoder files can be downloaded from the repository:

• model.pkl: The trained machine learning model
• encoder.pkl: The feature encoder for preprocessing

Usage

Basic Setup

from django_attack_blocker import MLIPBlocker
from django_attack_blocker import with_ip_blocking

# Initialize the blocker with your model
blocker = MLIPBlocker(
    model_path='path/to/model.pkl',
    encoder_path='path/to/encoder.pkl',
    block_threshold=0.8,  # Confidence threshold for blocking
    block_timeout=3600,   # Block duration in seconds
    trusted_ips=['127.0.0.1', '192.168.1.0/24'],  # Always allow these IPs
    blocked_ips=['10.0.0.5']  # Always block these IPs
)

# Protect a view uisng decorator
@with_ip_blocking(blocker)
def my_protected_view(request):
    # Your view code here
    return JsonResponse({"status": "success"})

The complete list of parameters are shown in this table

Parameter	Type	Default	Description
model_path	string	Required	Path to the pickled ML model file (.pkl)
encoder_path	string	Required	Path to the pickled encoder file (.pkl)
block_threshold	float	0.5	Confidence threshold for blocking decisions (0.0-1.0), where higher values require more confidence before blocking
block_timeout	int	None	Time duration in seconds for which an IP stays blocked. If None, blocks the IP permanently
trusted_ips	list	None	List of IP addresses or CIDR ranges (e.g. '192.168.1.0/24') that will always be allowed
blocked_ips	list	None	List of IP addresses or CIDR ranges that will always be blocked

Note: The model and encoder files (model.joblib and encoder.pkl) can be found in the weights directory of the repository.

The model expects logs in a specific format, with the following columns required:

dur, proto, service, state, spkts, dpkts, sbytes, dbytes, rate, sttl, dttl,
sload, dload, sloss, dloss, sinpkt, dinpkt, sjit, djit, swin, stcpb, dtcpb,
dwin, tcprtt, synack, ackdat, smean, dmean, trans_depth, response_body_len,
ct_srv_src, ct_state_ttl, ct_dst_ltm, ct_src_dport_ltm, ct_dst_sport_ltm,
ct_dst_src_ltm, is_ftp_login, ct_ftp_cmd, ct_flw_http_mthd, ct_src_ltm,
ct_srv_dst, is_sm_ips_ports

Sample Request Body

The request body should contain a "log" object with the network traffic features:

{
  "log": {
    "dur": 0.0,
    "proto": 0,
    "service": 0,
    "state": 1,
    "spkts": 1,
    "dpkts": 0,
    "sbytes": 2048,
    "dbytes": 0,
    "rate": 0,
    "sttl": 64,
    "dttl": 64,
    "sload": 0.0,
    "dload": 0.0,
    "sloss": 0,
    "dloss": 0,
    "sinpkt": 0.0,
    "dinpkt": 0.0,
    "sjit": 0.0,
    "djit": 0.0,
    "swin": 65535,
    "dwin": 65535,
    "stcpb": 0,
    "dtcpb": 0,
    "tcprtt": 0.0,
    "synack": 0.0,
    "ackdat": 0.0,
    "smean": 2048,
    "dmean": 0,
    "trans_depth": 1,
    "response_body_len": 0,
    "ct_srv_src": 1,
    "ct_state_ttl": 1,
    "ct_dst_ltm": 1,
    "ct_src_dport_ltm": 1,
    "ct_dst_sport_ltm": 1,
    "ct_dst_src_ltm": 1,
    "ct_src_ltm": 1,
    "ct_srv_dst": 1,
    "is_ftp_login": 0,
    "ct_ftp_cmd": 0,
    "ct_flw_http_mthd": 1,
    "is_sm_ips_ports": 0
  }
}

Advanced Usage

Manual IP Management

# Manually block an IP address temporarily
blocker.block_ip('192.168.1.100', duration=3600)  # Block for 1 hour

# Permanently block an IP address
blocker.block_ip('192.168.1.101')

# Unblock an IP address
blocker.unblock_ip('192.168.1.100')

Getting Statistics

# Get statistics about blocked requests
stats = blocker.get_stats()
print(stats)

UNSW Dataset

This library is designed to work with models trained on the UNSW-NB15 dataset, which contains a wide range of network attacks such as:

• Fuzzers
• Analysis
• Backdoors
• DoS
• Exploits
• Generic
• Reconnaissance
• Shellcode
• Worms

The library blocks that address either permanently in a session or caches it for the specified block time. Default is to be blocked permanently, till next restart of the server.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.