npm package: @madkudu-core-tools/vulnerator
Description: Tool to scan and filter vulnerabilities using AWS CLI with terminal, JSON, and HTML output options. Supports filtering for fixable vulnerabilities only.
Author: MadKudu
Latest version: 2.1.0

# @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

```bash
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:

```bash
# 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:

```bash
# 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:

```bash
# 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

```bash
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:

```json
{
  "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:

```typescript
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

```bash
# 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