🛡️ Troj3n

Antivirus for Node.js projects

Scan for infected files and malicious/vulnerable packages with real-time protection

✨ Features

• 🔍 File Scanning - Detect infected files with suspicious patterns, obfuscated code, and malware
• 📦 Package Scanning - Identify malicious and vulnerable npm packages
• ⏱️ Periodic Scanning - Automatic scans every 5 minutes (configurable)
• 🎯 TypeScript Support - Full type safety with excellent IDE integration
• 🚨 Automated Rules - Delete infected files, update packages, or stop servers automatically
• 📊 Detailed Reporting - Get comprehensive scan results with severity levels
• 🎨 Beautiful Logging - Colored console output for easy monitoring

📦 Installation

npm install troj3n

🚀 Quick Start

JavaScript

import troj3n from "troj3n";

// Run with default options (scans files and packages every 5 minutes)
const { results, stop } = await troj3n();

// Stop periodic scanning when needed
stop();

TypeScript

import troj3n, { type Troj3nOptions, type ScanResults } from "troj3n";

// Run with default options
const { results, stop } = await troj3n();

// Stop periodic scanning when needed
stop();

📖 Usage

Basic Usage

import troj3n from "troj3n";

// Default scan (files + packages, logging enabled, scans every 5 minutes)
const { results, stop } = await troj3n();

// Stop periodic scanning
stop();

Periodic Scanning

By default, troj3n runs scans every 5 minutes. You can customize the interval:

// Scan every 30 seconds
const { results, stop } = await troj3n({
  scanEvery: "30s",
});

// Scan every 10 minutes
const { results, stop } = await troj3n({
  scanEvery: "10m",
});

// Scan every hour
const { results, stop } = await troj3n({
  scanEvery: "1h",
});

// Run once (disable periodic scanning)
const results = await troj3n({
  scanEvery: "",
});

Time Format: Use a number followed by a unit:

• s = seconds (e.g., "30s")
• m = minutes (e.g., "5m")
• h = hours (e.g., "1h")

Custom Scopes

// Scan only files
await troj3n({
  scopes: ["files"],
});

// Scan only packages
await troj3n({
  scopes: ["packages"],
});

// Scan both (default)
await troj3n({
  scopes: ["files", "packages"],
});

Disable Logging

const { results, stop } = await troj3n({
  logging: false,
});

Execute Rules

// Delete infected files automatically
const { results, stop } = await troj3n({
  rules: {
    deleteInfectedFiles: true,
  },
});

// Delete infected files and stop the server
const { results, stop } = await troj3n({
  rules: {
    deleteInfectedFilesAndStop: true,
  },
});

// Update/fix packages and stop the server
const { results, stop } = await troj3n({
  rules: {
    updatePackagesAndStop: true,
  },
});

Complete Example

JavaScript

import troj3n from "troj3n";

// Periodic scanning (default: every 5 minutes)
const { results, stop } = await troj3n({
  scopes: ["files", "packages"],
  logging: true,
  scanEvery: "5m", // or "30s", "1h", etc.
  rules: {
    deleteInfectedFiles: false,
    deleteInfectedFilesAndStop: false,
    updatePackagesAndStop: false,
  },
});

console.log("Infected files:", results.infectedFiles);
console.log("Vulnerable packages:", results.vulnerablePackages);
console.log("Malicious packages:", results.maliciousPackages);

// Stop periodic scanning when needed
stop();

TypeScript

import troj3n, {
  type Troj3nOptions,
  type ScanResults,
  type InfectedFile,
  type VulnerablePackage,
  type MaliciousPackage,
} from "troj3n";

const options: Troj3nOptions = {
  scopes: ["files", "packages"],
  logging: true,
  scanEvery: "5m", // Periodic scanning every 5 minutes
  rules: {
    deleteInfectedFiles: false,
    deleteInfectedFilesAndStop: false,
    updatePackagesAndStop: false,
  },
};

// With periodic scanning enabled, returns { results, stop }
const { results, stop } = await troj3n(options);

// TypeScript provides full type safety and autocomplete
results.infectedFiles.forEach((file: InfectedFile) => {
  console.log(`File: ${file.path}, Severity: ${file.severity}`);
  file.issues.forEach((issue) => console.log(`  - ${issue}`));
});

results.vulnerablePackages.forEach((pkg: VulnerablePackage) => {
  console.log(`${pkg.name}@${pkg.version}: ${pkg.vulnerability}`);
});

// Stop periodic scanning
stop();

📚 API Reference

troj3n(options)

Parameters

• options (Troj3nOptions, optional)
  • scopes (ScanScope[], optional): Scopes to scan
    • 'files': Scan for infected files in the project
    • 'packages': Scan for malicious/vulnerable packages
    • Default: ['files', 'packages']
  • logging (boolean, optional): Enable/disable logging
    • Default: true
  • rules (Rules, optional): Rules to execute
    • deleteInfectedFiles (boolean, default: false): Delete infected files
    • deleteInfectedFilesAndStop (boolean, default: false): Delete infected files and stop the server
    • updatePackagesAndStop (boolean, default: false): Update/fix npm packages and stop the server
  • scanEvery (string, optional): Run scans periodically at the specified interval
    • Format: number + unit (s=seconds, m=minutes, h=hours)
    • Examples: "5m", "30s", "1h", "10m"
    • Default: "5m" (scans every 5 minutes)
    • Set to empty string "" to disable periodic scanning (run once)

Returns

• If scanEvery is set (default: "5m"): Promise<{ results: ScanResults; stop: () => void }>
  • results: Scan results object
  • stop: Function to stop periodic scanning
• If scanEvery is empty/disabled: Promise<ScanResults>

ScanResults - Object containing:

• infectedFiles (InfectedFile[]): List of infected files found
  • path (string): Full path to the infected file
  • issues (string[]): List of detected issues
  • severity ('low' | 'medium' | 'high'): Severity level
• vulnerablePackages (VulnerablePackage[]): List of vulnerable packages found
  • name (string): Package name
  • version (string): Package version
  • vulnerability (string, optional): Description of the vulnerability
  • severity (string, optional): Severity of the vulnerability
• maliciousPackages (MaliciousPackage[]): List of malicious packages found
  • name (string): Package name
  • version (string): Package version

TypeScript Types

All types are exported for use in TypeScript projects:

import type {
  Troj3nOptions,
  ScanResults,
  InfectedFile,
  VulnerablePackage,
  MaliciousPackage,
  Rules,
  ScanScope,
  Severity,
} from "troj3n";

🔍 What Gets Scanned?

File Scanning

Scans JavaScript/TypeScript files for:

• ✅ Suspicious code patterns (eval, Function constructor, etc.)
• ✅ Obfuscated code detection
• ✅ Base64 encoded suspicious content
• ✅ Malicious network requests
• ✅ File system manipulation attempts
• ✅ Process execution attempts

Package Scanning

Scans npm packages for:

• ✅ Known malicious packages
• ✅ Vulnerable packages (using npm audit)
• ✅ Suspicious package names
• ✅ Typosquatting patterns

⚙️ Default Behavior

• Scopes: Scans both files and packages by default
• Logging: Enabled by default
• Rules: All rules are disabled by default (set to false)
• Periodic Scanning: Enabled by default, scans every 5 minutes (scanEvery: "5m")

💻 TypeScript Support

Troj3n is written in TypeScript and provides full type definitions. When using TypeScript, you'll get:

• ✅ Full type safety - All parameters and return values are typed
• ✅ IntelliSense support - Autocomplete for all options and properties
• ✅ Hover documentation - JSDoc comments appear when hovering over functions and types
• ✅ Type checking - Catch errors at compile time

The package works seamlessly with both JavaScript and TypeScript projects.

🛠️ Development

To build the project from source:

# Install dependencies
npm install

# Build TypeScript
npm run build

📋 Requirements

• Node.js >= 14.0.0
• npm (for package vulnerability scanning)

🤝 Contributing

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

📄 License

MIT License - see LICENSE file for details.

⭐ Show Your Support

If you find this project helpful, please consider giving it a star on GitHub!