Security Nodes

Protect against malware and threats with virus scanning.

Required Plugin

Plugin Required

Security nodes require a plugin to execute. You must install and provide the security plugin.

Available Plugin

Plugin	Package	Operations	Requirements
virusScanPlugin	@uploadista/flow-security-clamscan	Virus scanning, malware detection	ClamAV installed on system

Installation

npm

npm install @uploadista/flow-security-nodes @uploadista/flow-security-clamscan

pnpm

pnpm add @uploadista/flow-security-nodes @uploadista/flow-security-clamscan

yarn

yarn add @uploadista/flow-security-nodes @uploadista/flow-security-clamscan

import { createUploadistaServer } from "@uploadista/server";
import { virusScanPlugin } from "@uploadista/flow-security-clamscan";

const uploadista = await createUploadistaServer({
  // ...
  plugins: [
    virusScanPlugin(),
  ],
});

System Requirements

ClamAV must be installed on your system. It can run in two modes:

1. clamd daemon (recommended): Faster, persistent scanning service
2. clamscan binary: Slower but works without daemon

Ubuntu/Debian

sudo apt-get update
sudo apt-get install clamav clamav-daemon
sudo freshclam  # Update virus definitions
sudo systemctl enable clamav-daemon
sudo systemctl start clamav-daemon

macOS

brew install clamav
freshclam  # Update virus definitions

Docker

FROM node:24-slim
RUN apt-get update && apt-get install -y clamav clamav-daemon
RUN freshclam
RUN mkdir -p /var/run/clamav && chown clamav:clamav /var/run/clamav
CMD ["node", "dist/index.js"]

Plugin Configuration

import { createUploadistaServer } from "@uploadista/server";
import { virusScanPlugin } from "@uploadista/flow-security-clamscan";

// Default configuration (daemon preferred, fallback to binary)
const uploadista = await createUploadistaServer({
  plugins: [virusScanPlugin()],
});

// Custom daemon configuration
const uploadistaCustom = await createUploadistaServer({
  plugins: [
    virusScanPlugin({
      preference: "clamdscan",
      clamdscan_socket: "/var/run/clamav/clamd.sock",
      clamdscan_port: 3310,
      debug_mode: false,
    }),
  ],
});

// TCP connection instead of socket
const uploadistaTcp = await createUploadistaServer({
  plugins: [
    virusScanPlugin({
      preference: "clamdscan",
      clamdscan_host: "localhost",
      clamdscan_port: 3310,
    }),
  ],
});

Configuration Options

Option	Type	Default	Description
preference	"clamdscan" | "clamscan"	"clamdscan"	Scanning method
clamdscan_socket	string	system default	Daemon socket path (Unix)
clamdscan_host	string	-	TCP host (alternative to socket)
clamdscan_port	number	3310	TCP port
remove_infected	boolean	false	Remove infected files (not recommended in flows)
debug_mode	boolean	false	Enable debug logging

Performance

Mode	Latency
Daemon (clamdscan)	~100-500ms for small files (<1MB)
Binary (clamscan)	~1-3s per scan (slower, requires process startup)

---

Scan Virus Node

Scan files for viruses and malware using ClamAV.

Requires Plugin

VirusScanPlugin - Use @uploadista/flow-security-clamscan (requires ClamAV)

Package: @uploadista/flow-security-nodes

import { createScanVirusNode } from "@uploadista/flow-security-nodes";

// Fail flow if virus detected (recommended for production)
const scanNode = yield* createScanVirusNode("scan-1", {
  action: "fail",
  timeout: 60000,
});

// Continue with metadata (useful for logging/auditing)
const auditNode = yield* createScanVirusNode("scan-2", {
  action: "pass",
  timeout: 120000,
});

// With keepOutput option
const keepOutputNode = yield* createScanVirusNode("scan-3", {
  action: "fail",
}, {
  keepOutput: true,
});

Parameters

Parameter	Type	Required	Default	Description
action	"fail" | "pass"	No	"fail"	Action when virus detected
timeout	number (1000-300000)	No	60000	Max scan time in milliseconds

Options

Option	Type	Default	Description
keepOutput	boolean	false	Keep output in flow results

Actions

Action	Description
fail	Stop flow execution when virus detected (recommended for production)
pass	Continue processing with detection metadata (useful for logging/auditing)

Scan Results Metadata

All scan results are stored in file.metadata.virusScan:

type VirusScanMetadata = {
  scanned: boolean;        // Whether file was scanned
  isClean: boolean;        // Whether file is clean (no viruses)
  detectedViruses: string[]; // Array of detected virus names
  scanDate: string;        // ISO 8601 timestamp
  engineVersion: string;   // Antivirus engine version
  definitionsDate: string; // Virus definitions date
};

Error Codes

Error Code	Description
VIRUS_DETECTED	Malware found in file (when action=fail)
CLAMAV_NOT_INSTALLED	ClamAV not available on system
VIRUS_SCAN_FAILED	Generic scanning operation failure
SCAN_TIMEOUT	Scanning exceeded timeout limit

---

Example Flow

import { createUploadistaServer } from "@uploadista/server";
import { virusScanPlugin } from "@uploadista/flow-security-clamscan";
import { imagePlugin } from "@uploadista/flow-images-sharp";

// Configure server with both plugins
const uploadista = await createUploadistaServer({
  dataStore: s3Store({ /* ... */ }),
  kvStore: redisKvStore({ /* ... */ }),
  plugins: [
    virusScanPlugin(),
    imagePlugin(),
  ],
});

// Create a flow that scans before processing
// Flow: Input -> Scan -> Resize -> Store

---

Security Pipeline Pattern

Input -> Scan Virus -> Conditional (clean?)
         |-- YES: Process -> Store
         |-- NO: Quarantine / Reject

---

Virus Definitions

ClamAV uses virus definition databases that must be kept up-to-date.

Update Virus Definitions

# Update manually
sudo freshclam

# Set up automatic updates (cron)
# Add to crontab:
0 */6 * * * /usr/bin/freshclam --quiet

Docker

In your Dockerfile, update definitions at build time:

RUN freshclam

For production, set up a cron job or scheduled task to run freshclam regularly.

---

Testing

You can test virus detection using the EICAR test file - a harmless file that all antivirus software detects as malware:

// EICAR test string (safe, not actual malware)
const eicarTest = new TextEncoder().encode(
  'X5O!P%@AP[4\\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*'
);

const result = yield* virusScanPlugin.scan(eicarTest);
// result.isClean === false
// result.detectedViruses === ["Eicar-Test-Signature"]

---

Troubleshooting

“ClamAV is not installed or not available”

• Verify ClamAV is installed: clamscan --version
• Check daemon is running: systemctl status clamav-daemon (Linux)
• Try using binary mode: preference: "clamscan"

“Connection refused” / Daemon not responding

• Ensure daemon is running: sudo systemctl start clamav-daemon
• Check socket path matches your system’s configuration
• Try TCP connection instead of socket

Scan timeout

• Increase timeout in scan virus node parameters
• Consider using daemon mode (faster than binary)
• Check system resources (CPU, memory)

Outdated virus definitions

# Check definitions age
freshclam --version

# Update definitions
sudo freshclam

---

Related

• Plugins Concept - How plugins work
• Flow Nodes Overview - All available nodes