@madkudu-core-tools/vulnerator

A comprehensive CLI tool for scanning security vulnerabilities in AWS environments. Supports both container image vulnerabilities and EC2 instance vulnerabilities using AWS Inspector2.

Installation

npm install -g @madkudu-core-tools/vulnerator

Usage

The tool supports two main scanning modes:

Container Image Scanning

Scan container images deployed in ECS services:

# Scan using cluster name as service name (service parameter is optional)
mct-vulnerator image --cluster production-cluster
mct-vulnerator image -c api-public

# Scan specific service in cluster
mct-vulnerator image --cluster production-cluster --service myapp
mct-vulnerator image -c api-public -s my-service

# Generate JSON report (service optional)
mct-vulnerator image -c production-cluster -j image-vulnerabilities.json
mct-vulnerator image --cluster production-cluster --service myapp --json-output myapp-image-report.json

# Generate HTML report
mct-vulnerator image -c production-cluster --html-output myapp-image-report.html

# Filter for fixable vulnerabilities only
mct-vulnerator image -c production-cluster --fixable-only
mct-vulnerator image -c production-cluster -s myapp -f

EC2 Instance Scanning

Scan EC2 instances within ECS clusters:

# Terminal output
mct-vulnerator instance --cluster argo
mct-vulnerator instance -c production-cluster

# Generate JSON report
mct-vulnerator instance -c argo -j instance-vulnerabilities.json
mct-vulnerator instance --cluster argo --json-output argo-instance-report.json

# Generate HTML report
mct-vulnerator instance -c argo --html-output argo-instance-report.html

# Filter for fixable vulnerabilities only
mct-vulnerator instance -c argo --fixable-only
mct-vulnerator instance -c argo -f

Vulnerability Fixing Runbook

Display the comprehensive vulnerability fixing guide:

# Show the complete vulnerability fixing runbook
mct-vulnerator llm

This command displays the detailed vulnerability fixing runbook that provides step-by-step instructions for:

• Setting up the environment and prerequisites
• Generating vulnerability reports
• Fixing Docker image vulnerabilities
• Fixing application dependency vulnerabilities
• Instance vulnerability remediation
• Creating comprehensive pull requests

Common Options

Both image and instance commands support:

• -j, --json-output <file>: Save results to JSON file instead of displaying in terminal
• --html-output <file>: Generate HTML report with all vulnerability details
• -f, --fixable-only: Show only fixable vulnerabilities
• --help: Display help for command

Required parameters:

• The image command requires: -c, --cluster <cluster-name> (service defaults to cluster name if not specified)
• The instance command requires: -c, --cluster <cluster-name>

Command Structure

mct-vulnerator <command> [options]

Commands:

• image: Scan container image vulnerabilities for ECS services (requires --cluster, --service is optional)
• instance: Scan EC2 instance vulnerabilities in an ECS cluster (requires --cluster)
• llm: Display the vulnerability fixing runbook for LLM assistance

Required Parameters:

• For image: --cluster <name> is required, --service <name> is optional (defaults to cluster name)
• For instance: --cluster <name> is required
• For llm: No parameters required

Features

Common Features

• ✅ AWS Inspector2 integration for accurate vulnerability assessments
• ✅ Multiple output formats: Terminal, JSON, and interactive HTML reports
• ✅ Fix status classification (fixable vs non-fixable vulnerabilities)
• ✅ Filtering options to show only fixable vulnerabilities
• ✅ Severity analysis (Critical, High, Medium, Low, Informational)
• ✅ Comprehensive error handling and user-friendly messages
• ✅ TypeScript support with full type definitions

Image Scanning Features

• ✅ Direct ECS cluster and service targeting
• ✅ Container image vulnerability detection
• ✅ Package-level vulnerability details with file paths
• ✅ Support for multiple package managers (npm, pip, etc.)
• ✅ Simplified command structure with explicit parameters

Instance Scanning Features

• ✅ Automatic EC2 instance discovery from ECS clusters
• ✅ System-level vulnerability detection
• ✅ Platform-specific resource counting (Amazon Linux vs Others)
• ✅ Vulnerability deduplication across multiple instances

Prerequisites

• Node.js 18+
• AWS CLI configured with appropriate permissions
• Access to AWS ECS and Inspector2 services

Required AWS Permissions

Your AWS credentials need the following permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecs:ListClusters",
        "ecs:ListServices",
        "ecs:DescribeServices",
        "ecs:DescribeTaskDefinition",
        "ecs:ListContainerInstances",
        "ecs:DescribeContainerInstances",
        "inspector2:ListFindings"
      ],
      "Resource": "*"
    }
  ]
}

API

You can also use this package programmatically:

import {
  scanProject,
  scanInstances,
  findEcsService,
  getEcsImage,
  getEcrVulnerabilities,
  getInstanceVulnerabilities,
} from "@madkudu-core-tools/vulnerator";

// High-level API
// Scan container images (cluster required, service optional - defaults to cluster name)
scanProject({ 
  clusterOverride: "production-cluster", 
  serviceOverride: "myapp", // Optional - uses cluster name if not specified
  jsonOutput: "results.json" 
});

// Scan EC2 instances (cluster required)
scanInstances({ 
  clusterOverride: "argo", 
  htmlOutput: "report.html" 
});

// Low-level API for custom workflows
// Image scanning
const ecsService = findEcsService("production-cluster", "myapp");
const imageData = getEcsImage(ecsService.taskDefinition);
const imageVulnerabilities = getEcrVulnerabilities(
  imageData.repositoryName,
  imageData.tag
);

// Instance scanning
const instanceVulnerabilities = getInstanceVulnerabilities("argo");

How It Works

Image Scanning Workflow

1. ECS Service Targeting: Directly targets the specified ECS service in the specified cluster via required --cluster and --service parameters
2. Image Identification: Extracts the currently deployed container image tag
3. Vulnerability Scanning: Queries AWS Inspector2 for vulnerabilities in that specific image
4. Report Generation: Formats results according to your specified output format

Instance Scanning Workflow

1. Cluster Discovery: Identifies the specified ECS cluster
2. Instance Enumeration: Lists all EC2 instances within the cluster
3. Vulnerability Scanning: Queries AWS Inspector2 for vulnerabilities across all instances
4. Deduplication: Removes duplicate vulnerabilities by ID/name
5. Platform Analysis: Categorizes vulnerabilities by resource platform (Amazon Linux vs Others)
6. Report Generation: Formats results with platform-specific counts

Output Formats

Terminal Output

Image Scanning:

• Container image summary (repository, tag)
• Vulnerability counts by severity
• Table format showing top vulnerabilities with package details

Instance Scanning:

• Cluster and instance information
• Platform distribution (Amazon Linux vs Others)
• Table format showing top vulnerabilities with affected resources

JSON Output

Image Scanning:

• Complete vulnerability details with package information
• File paths and package manager details
• Structured data for automation and integration

Instance Scanning:

• Vulnerability details with affected resource information
• Platform-specific resource counts (amazonResourceAffectedCount, otherResourceAffectedCount)
• Instance IDs and platform details for each vulnerability

HTML Output

• Interactive web reports for both scanning types
• Collapsible sections for easy navigation
• Visual separation of fixable vs non-fixable vulnerabilities
• Detailed vulnerability information with type-specific details

Development

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Run tests
pnpm test

# Run tests in watch mode
pnpm run test:watch

# Lint code
pnpm run lint

License

MIT