🛡️ BitSafe AI - Report Generator Core

High-Performance Network Security Reporting Microservice

BitSafe AI Report Generator is a robust Go-based microservice designed to analyze network traffic logs, assess security risks using Local LLMs (Phi-3.5), and generate professional PDF reports.

It acts as a "heavy-lifting worker" for the main application, offloading CPU-intensive tasks—such as AI inference and headless browser rendering—from the main backend.

🚀 Key Features

• ⚡ High Performance: Built with Go and Fiber to ensure minimal latency and maximum throughput.

• 🧠 Local AI Analysis: Seamlessly integrates with Ollama (phi3.5) to generate executive summaries, risk personas, and remediation steps without sending sensitive data to the cloud.

• 🛑 Context-Based Hard Cancel: Features a sophisticated job management system that allows for the instant termination of heavy tasks (even during AI inference). This is critical for freeing up resources on constrained hardware (e.g., N100 Mini PCs).

• 📄 High-Fidelity PDF: Utilizes ChromeDP (Headless Chrome) to render pixel-perfect HTML/CSS reports complete with Chart.js visualizations.

• 🔗 Webhook Integration: Implements an asynchronous architecture that notifies the main backend via Webhooks once processing is complete.

📦 Project Structure

The project follows a modular "Separation of Concerns" architecture for easy maintenance:

• api/: HTTP Handlers (Generate/Cancel) and Job Manager.

• models/: Data Structures (Report, Device, Domains, Metrics) and AI Request/Response models.

• main.go: Application entry point.

• logic.go: Main Business Logic (Controller Layer).

• ai.go: Ollama (Phi-3.5) Integration Logic.

• pdf.go: ChromeDP PDF Generation and HTML Template.

• utils.go: Helper functions (Webhook, Parsing, Context checks).

• go.mod: Go Module Definition.

🛠️ Prerequisites

• Go: Version 1.21 or higher.

• Google Chrome / Chromium: Must be installed on the host machine (required for PDF rendering).

• Ollama: Must be installed and running locally.

  • Required Model: phi3.5

  • Pull Command: ollama pull phi3.5

⚙️ Installation & Running

1. Clone the Repository

git clone https://github.com/uslanozan/bitsafe-report-generator.gitcd bitsafe-report-generator

2. Install Dependencies

go mod tidy

3. Start the Service

go run .

(The service will start listening on port 9595)

🔌 API Documentation

1. Generate Report

Initiates the analysis and PDF generation process. Returns 202 Accepted immediately to prevent blocking the main backend.

• Endpoint: POST /generate

• URL: http://localhost:9595/generate

• Content-Type: application/json

Request Body Example:

{
  "reportId": 48,
  "data": {
    "device": {
      "id": "device-uuid",
      "name": "ozy-minipc",
      "ip": "192.168.1.42"
    },
    "report": {
      "generated_at": "2025-12-11 12:45",
      "overall_risk_score": 82,
      "total_traffic": "3.85 GB",
      "time_window": { "from": "...", "to": "..." }
    },
    "domains": [ ... ],
    "metrics": { ... },
    "anomalies": [ ... ]
  }
}

Response:

{
  "status": "accepted",
  "message": "Report generation process started."
}

2. Cancel Report (Hard Stop)

Instantly kills the running process (AI or PDF generation) for a specific Report ID using Go Context. This is critical for resource management.

• Endpoint: POST /cancel

• URL: http://localhost:9595/cancel

• Content-Type: application/json

Request Body Example:

{
  "reportId": 101
}

Response:

{
  "status": "cancelled",
  "message": "Process cancelled."
}

3. Webhook Callback

When the job is finished (either success or failure), this service sends a POST request to the main backend.

• Target URL: POST http://localhost:3000/webhook/report-finished (Default)

Success Payload Example:

{
  "reportId": 48,
  "status": "success",
  "filePath": "public/reports/ozy-minipc_101.pdf",
  "error": ""
}

Failure Payload Example:

{
  "reportId": 48,
  "status": "failed",
  "filePath": "",
  "error": "JSON Parsing Error / AI Connection Failed"
}

🧪 Testing (with cURL)

You can manually test the service logic using the terminal.

1. Start Generation:

curl -X POST http://localhost:9595/generate -H "Content-Type: application/json" -d @mock.json

2. Cancel Generation (Run immediately after starting):

curl -X POST http://localhost:9595/cancel -H "Content-Type: application/json" -d '{"reportId": 101}'