vulnmatter-extension/cli-version/README.md

VS Code extension for CVE vulnerability analysis using the VulnMatter API with X-API-Key. See CHANGELOG.md for release notes.

# VulnMatter CLI

A command-line interface tool for interacting with the VulnMatter API to analyze CVE vulnerabilities and generate security reports.

## Installation

### From npm (if published)
```bash
npm install -g vulnmatter-cli
```

### From source
```bash
git clone https://github.com/jeffrycascate/singularity-convert.git
cd singularity-convert/VSCode
npm install
npm link
```

## Configuration

Before using the CLI, you need to configure your VulnMatter API key:

```bash
# Set your API key
vulnmatter-cli config set-key <your-api-key>

# Optional: Set custom API URL (if using a different instance)
vulnmatter-cli config set-url https://your-api-instance.com

# View current configuration
vulnmatter-cli config show
```

You can also set the API key using an environment variable:
```bash
export VULNMATTER_API_KEY="your-api-key"
```

## Usage

### Get CVE Risk Scores

Get risk scores for one or more CVEs:

```bash
# Single CVE
vulnmatter-cli scores CVE-2023-12345

# Multiple CVEs
vulnmatter-cli scores CVE-2023-12345 CVE-2024-67890

# Output as JSON
vulnmatter-cli scores CVE-2023-12345 --format json

# Save to file
vulnmatter-cli scores CVE-2023-12345 --output scores.json
```

### Generate CVE Reports

Generate comprehensive reports for CVEs:

```bash
# Basic report
vulnmatter-cli report CVE-2023-12345

# Multiple CVEs
vulnmatter-cli report CVE-2023-12345 CVE-2024-67890

# With additional parameters
vulnmatter-cli report CVE-2023-12345 --postfix "format=pdf&detailed=true"

# Save report details to file
vulnmatter-cli report CVE-2023-12345 --output report.json
```

### Complete Analysis

Get both scores and generate reports in one command:

```bash
# Analyze CVEs (scores + report)
vulnmatter-cli analyze CVE-2023-12345 CVE-2024-67890

# With custom format and output
vulnmatter-cli analyze CVE-2023-12345 --format json --output analysis.json

# With report parameters
vulnmatter-cli analyze CVE-2023-12345 --postfix "detailed=true" --output results.json
```

### Analyze from File

Analyze CVEs listed in a file (one CVE per line):

```bash
# Create a file with CVEs
echo "CVE-2023-12345" > cves.txt
echo "CVE-2024-67890" >> cves.txt

# Analyze all CVEs in the file
vulnmatter-cli from-file cves.txt

# Run specific command on file CVEs
vulnmatter-cli from-file cves.txt --command scores --format json
vulnmatter-cli from-file cves.txt --command report --postfix "format=pdf"
```

## Commands

### `config`
Manage configuration settings.

- `set-key <apiKey>` - Set the VulnMatter API key
- `set-url <url>` - Set the API base URL
- `show` - Display current configuration

### `scores <cves...>`
Get risk scores for CVEs.

Options:
- `-f, --format <type>` - Output format: json, table (default: table)
- `-o, --output <file>` - Save output to file

### `report <cves...>`
Generate comprehensive reports for CVEs.

Options:
- `-p, --postfix <string>` - Additional query parameters
- `-o, --output <file>` - Save report details to file

### `analyze <cves...>`
Get both scores and generate reports for CVEs.

Options:
- `-f, --format <type>` - Output format for scores: json, table (default: table)
- `-p, --postfix <string>` - Additional query parameters for report
- `-o, --output <file>` - Save complete results to file

### `from-file <file>`
Analyze CVEs from a file (one CVE per line).

Options:
- `-c, --command <cmd>` - Command to run: scores, report, analyze (default: analyze)
- `-f, --format <type>` - Output format: json, table (default: table)
- `-p, --postfix <string>` - Additional query parameters for report
- `-o, --output <file>` - Save results to file

## Examples

### Basic Usage
```bash
# Get scores for a CVE
vulnmatter-cli scores CVE-2023-12345

# Generate a report
vulnmatter-cli report CVE-2023-12345

# Complete analysis
vulnmatter-cli analyze CVE-2023-12345
```

### Batch Processing
```bash
# Create a file with multiple CVEs
cat > vulnerable_cves.txt << EOF
CVE-2023-12345
CVE-2023-23456
CVE-2024-34567
# This is a comment and will be ignored
CVE-2024-45678
EOF

# Analyze all CVEs from file
vulnmatter-cli from-file vulnerable_cves.txt --output batch_analysis.json
```

### JSON Output
```bash
# Get scores as JSON
vulnmatter-cli scores CVE-2023-12345 --format json

# Complete analysis with JSON output
vulnmatter-cli analyze CVE-2023-12345 --format json --output results.json
```

## Output Formats

### Table Format (Default)
```
┌─────────────────┬────────────┐
│ CVE             │ Risk Score │
├─────────────────┼────────────┤
│ CVE-2023-12345  │ 8.50       │
│ CVE-2024-67890  │ 7.20       │
└─────────────────┴────────────┘
```

### JSON Format
```json
{
  "CVE-2023-12345": 8.5,
  "CVE-2024-67890": 7.2
}
```

## Error Handling

The CLI provides helpful error messages:

- Invalid CVE format validation
- Missing API key guidance
- Network connectivity issues
- API error responses

## Environment Variables

- `VULNMATTER_API_KEY` - Your VulnMatter API key (alternative to config)

## Development

### Building from Source
```bash
git clone https://github.com/jeffrycascate/singularity-convert.git
cd singularity-convert/VSCode
npm install
```

### Testing
```bash
# Link for local development
npm link

# Test the CLI
vulnmatter-cli --help
```

## License

This project is licensed under the terms specified in the repository.

## Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

## Support

For issues related to the VulnMatter API, please refer to the VulnMatter documentation.
For CLI-specific issues, please open an issue in this repository.