Whitelist Assessment Tool (Threat Analyzer)

Overview

The Whitelist Assessment Tool is an internal analysis utility integrated with the Eyeglass appliance that processes threat-analyzer CSV reports and generates actionable insights for ransomware defense tuning and whitelist validation.

The tool analyzes filesystem activity captured by the threat analyzer and produces structured summaries to help administrators:

• Identify common users and service accounts
• Detect recurring path patterns
• Analyze file extensions frequently accessed
• Detect automation patterns
• Generate recommended whitelist candidates
• Produce PDF or HTML reports for review and audit purposes

The tool helps security teams reduce false positives while maintaining effective ransomware detection policies.

Purpose

Threat detection systems can generate alerts for legitimate automation or service activity.

The Whitelist Assessment Tool helps determine:

• Which activity patterns are expected
• Which behaviors represent automation or service processes
• Which activity should be whitelisted safely

This prevents:

• Unnecessary alert noise
• Operational interruptions
• Service automation disruptions

Architecture

The tool is implemented as a Node.js web application that runs locally on the Eyeglass appliance.

Components

Component	Description
Node.js Backend	Handles CSV ingestion, analysis logic, and report generation
Web UI	Allows browsing CSV reports and running analysis
Analysis Engine	Processes events and generates summary metrics
Export Engine	Generates HTML and PDF reports
Optional AI Layer	Provides additional analysis if enabled

System Architecture

Threat Analyzer CSV Reports
        │
        │
        ▼
Whitelist Assessment Tool
(Node.js service :4000)
        │
        │
        ▼
Analysis Engine
        │
        ├── User activity analysis
        ├── Path pattern detection
        ├── Service account detection
        ├── Extension frequency analysis
        └── Whitelist recommendation logic
        │
        ▼
Analysis Reports
        │
        ├── Dashboard UI
        ├── PDF Export
        └── HTML Export

Accessing the Tool

Once installed on the Eyeglass appliance, the tool is accessible via:

http://<eyeglass-ip>:4000

The Eyeglass UI can include a button that opens the tool in a new browser tab.

Prerequisites

System Requirements

• Eyeglass appliance
• Node.js 18+
• npm
• Access to CSV reports directory

Verify Node installation:

node -v
npm -v

File Locations

Path	Purpose
/opt/superna/whitelist-tool	Application directory
/opt/data/log_reports	Default CSV source directory
/var/log/whitelist-tool.out.log	Service output log
/var/log/whitelist-tool.err.log	Service error log

Installation

Step 1 – Copy the Tool

Copy the tool to:

/opt/superna/whitelist-tool

Step 2 – Install Dependencies

cd /opt/superna/whitelist-tool
npm install

Step 3 – Configure Environment

Create environment configuration:

cp .env.example .env

Edit .env and configure:

Variable	Description
PORT	Server port (default 4000)
OPENAI_API_KEY	Optional AI analysis
LOCAL_CSV_ROOT	CSV report location
LOCAL_ALLOWED_PATHS	Allowed filesystem paths
DRIVE_UPLOAD	Enable Google Drive export

Running the Tool

Manual Start

node server.js

Access Web UI

http://localhost:4000

Running as a Service

The tool should run as a system service on the Eyeglass appliance.

Create systemd service:

sudo vi /etc/systemd/system/whitelist-tool.service

Paste:

[Unit]
Description=Whitelist Tool Node Server
After=network.target

[Service]
User=admin
WorkingDirectory=/opt/superna/whitelist-tool
ExecStart=/usr/bin/node server.js
Restart=always
RestartSec=5
Environment=NODE_ENV=production
EnvironmentFile=-/opt/superna/whitelist-tool/.env
StandardOutput=append:/var/log/whitelist-tool.out.log
StandardError=append:/var/log/whitelist-tool.err.log

[Install]
WantedBy=multi-user.target

Enable Service

sudo systemctl daemon-reload
sudo systemctl enable --now whitelist-tool.service

Check Status

systemctl status whitelist-tool.service

View Logs

tail -f /var/log/whitelist-tool.out.log
tail -f /var/log/whitelist-tool.err.log

Firewall Configuration

Open port 4000 for the service.

sudo firewall-cmd --permanent --add-port=4000/tcp
sudo firewall-cmd --reload

Using the Tool

Step 1 – Select CSV Report

Browse local reports under:

/opt/data/log_reports

Select the report to analyze.

Step 2 – Configure Analysis Settings

Available filters include:

Setting	Description
Date Filter	Restrict analysis timeframe
Maximum Path Depth	Controls path pattern grouping
Top Results Count	Limits results shown
Extra Service Patterns	Detect automation accounts
Exclusion Keys	Remove known noise patterns

Step 3 – Run Analysis

Click:

Run Analysis

The tool processes the CSV and generates reports.

Analysis Reports

Most Common Occurrences

Shows the most frequent:

• usernames
• source IPs
• accessed paths
• file extensions

This helps identify normal operational patterns.

Service Accounts

Detects accounts behaving like automation or scheduled jobs.

Typical examples:

• backup services
• monitoring agents
• deployment automation
• system tasks

These may be candidates for whitelisting.

Common Path Patterns

Detects directory patterns frequently accessed.

Example:

/ifs/data/backups/*
/ifs/system/tmp/*

These patterns help define safe directory-level exceptions.

Whitelist Suggestions

Based on aggregated behavior the tool suggests candidate entries such as:

• service accounts
• recurring directory paths
• automation file patterns

warning

These suggestions must be reviewed by administrators before implementation.

Organized Summary

A consolidated report showing:

• user activity clusters
• service accounts
• file extension trends
• path analysis

Average Events per Day

Provides a timeline showing activity trends.

Useful for identifying:

• spikes
• scheduled automation windows
• unusual bursts

Path Breakdown

Breaks activity by filesystem location.

Exporting Reports

The tool supports exporting results to:

• PDF: For audit documentation.
• HTML: For internal sharing or analysis.

Security Considerations

Secrets Management

The .env file contains sensitive information.

Never store it in source control.

File Access Restrictions

The application restricts filesystem reads to allowed directories defined in:

LOCAL_ALLOWED_PATHS

Network Exposure

The service runs on port 4000 and should only be accessible internally.

Recommended protections:

• firewall restrictions
• internal network access only
• VPN access if remote

Dependency Security

Node dependencies should be monitored regularly.

Check vulnerabilities using:

npm audit

Initial analysis shows:

0 vulnerabilities detected

Air-Gapped Environments

For environments without internet access:

• host front-end libraries locally
• disable AI analysis

Local copies required for:

• Bootstrap
• jQuery
• Chart.js
• jsPDF
• Font Awesome

Troubleshooting

Service Not Running

Check:

systemctl status whitelist-tool

Port Not Accessible

Verify firewall:

firewall-cmd --list-ports

Dependency Issues

Reinstall packages:

npm install

CSV Not Loading

Check permissions for:

/opt/data/log_reports

Logs

Review logs:

/var/log/whitelist-tool.out.log
/var/log/whitelist-tool.err.log

Future Advised Improvements

Potential enhancements include:

• direct integration with Eyeglass threat detection
• automatic whitelist generation
• scheduled analysis
• anomaly detection
• deeper AI behavioral analysis
• cluster comparison reports
• automated ransomware false-positive reduction

Maintenance

Regular maintenance tasks:

Task	Frequency
npm audit	quarterly
dependency updates	quarterly
service log review	monthly
whitelist rule validation	quarterly

Ownership

Tool originally developed by Valentin internally for Eyeglass threat analysis.

Maintained as part of internal security analysis tooling.