cyber-tds

Intelligent Cybersecurity Threat Detection System

Client Instructions

Prerequisites

• Bash shell environment

Setup Instructions

1. Make the setup script executable:

chmod +x setup.sh

2. Run the setup script:

./setup.sh

The setup script will:

• Install all required dependencies
• Configure the necessary environment variables
• Set up the client-side components

If you encounter any permission issues, you may need to run the script with sudo:

sudo ./setup.sh

Server Instructions

Prerequisites

• Docker installed on your system

Running with Docker

1. Build the Docker image:

docker build -t cyber-tds .

2. Run the container:

docker run -p 5050:5050 cyber-tds

The application will be accessible at http://localhost:5050

Running Tests

Prerequisites

• Python 3.x installed on your system
• All dependencies installed from requirements.txt

Running Tests Locally

1. Install test dependencies:

pip install -r requirements.txt

2. Run all tests:

python run_tests.py

Or run tests directly with pytest:

pytest -v

The tests include:

• Unit tests for API endpoints
• Edge case testing
• Error handling
• Integration tests
• Malware analysis tests
• Kafka integration tests
• Health check and utility function tests
• Batch processing tests

API Documentation

Base URL

http://localhost:5050

Authentication

All endpoints require Bearer token authentication in the header:

Authorization: Bearer YOUR_TOKEN

Endpoints

1. Health Check

Endpoint: /api/health
Method: GET
Description: Verifies if the service is running
Response:

{
    "status": "healthy"
}

Status Codes:

• 200: Service is healthy

2. Phishing Analysis (Single Email)

Endpoint: /api/phishing/analyze
Method: POST
Description: Analyzes a single email for phishing attempts
Request Body:

{
    "text": "Email content to analyze",
    "userid": "optional-user-id"
}

Response:

{
    "phishing": true/false,
    "score": 0-100,
    "details": {
        // Additional analysis details
    }
}

Status Codes:

• 200: Analysis successful
• 400: Missing or invalid request body
• 401: Missing or invalid authorization
• 500: Server error

3. Phishing Analysis (Batch)

Endpoint: /api/phishing/analyze/batch
Method: POST
Description: Analyzes multiple emails for phishing attempts
Request Body:

{
    "emails": [
        "First email content",
        "Second email content"
    ],
    "userid": "optional-user-id"
}

Response:

{
    "results": [
        {
            "phishing": true/false,
            "score": 0-100,
            "details": {
                // Additional analysis details
            }
        }
    ]
}

Status Codes:

• 200: Analysis successful
• 400: Missing or invalid request body
• 401: Missing or invalid authorization
• 500: Server error

4. Malware Analysis

Endpoint: /api/malware/analyse
Method: POST
Description: Analyzes a file for malware using both Cuckoo Sandbox and Yara rules
Request Body: Form data with file upload
Response:

{
    "status": "success/partial/error",
    "cuckoo_analysis": {
        "task_id": "string",
        "report": {
            // Cuckoo Sandbox analysis results
        }
    },
    "yara_analysis": {
        "status": "success/error",
        "results": [
            {
                "file": "path/to/scanned/file",
                "rule": "rule_name",
                "namespace": "rule_namespace",
                "tags": ["tag1", "tag2"],
                "description": "Rule description",
                "meta": {
                    // Rule metadata from YARA rule
                }
            }
        ]
    },
    "errors": {
        "cuckoo": "error message if any",
        "yara": "error message if any"
    }
}

Status Codes:

• 200: Analysis successful
• 400: No file provided or invalid file
• 401: Missing or invalid authorization
• 500: Server error

Error Responses

All endpoints may return error responses in the following format:

{
    "error": "Error message description"
}

Notes

1. The phishing analysis endpoints support both synchronous and asynchronous processing through Kafka
2. For large text inputs (>512 tokens), the phishing analysis is automatically chunked and processed
3. The malware analysis combines results from both Cuckoo Sandbox and Yara scanning
4. All endpoints require proper authentication with a Bearer token
5. The service runs on port 5050 by default