prismor 1.1.5
A CLI tool for scanning GitHub repositories for vulnerabilities, secrets, and generating SBOMs
Requires Python: >=3.7
Keywords: security scanning vulnerability sbom secrets github

# Prismor CLI

A powerful command-line tool for scanning GitHub repositories for security vulnerabilities, secrets, and generating Software Bill of Materials (SBOM).

**Get started at [https://prismor.dev](https://prismor.dev)** - Sign up for free to get your API key and access full dashboarding and analysis features!

## Features

- 🔍 **Vulnerability Scanning (scan)** - Detect security vulnerabilities in your codebase
- 🔐 **Secret Detection** - Find exposed secrets, API keys, and credentials
- 📦 **SBOM Generation** - Generate comprehensive Software Bill of Materials
- ⚡ **Full Scan** - Run all security checks in one command
- 🎨 **Beautiful CLI Output** - Colorful, easy-to-read results
- 🔗 **Flexible Repository Input** - Support for multiple GitHub URL formats including SSH, HTTPS, and bare domain formats

## Quick Start

1. **Sign up** at [https://prismor.dev](https://prismor.dev)
2. **Generate your API Key** from the dashboard
3. **Install** the CLI: `pip install prismor`
4. **Set your API key**: `export PRISMOR_API_KEY=your_api_key`
5. **Run your first scan**: `prismor --repo username/repo --fullscan`

For the complete analysis with dashboards and reports, visit [Prismor.dev](https://prismor.dev) after running scans!

## Installation

Install Prismor CLI via pip:

```bash
pip install prismor
```

## Prerequisites

### Getting Your API Key

Before using Prismor CLI, you need to get your API key from [Prismor.dev](https://prismor.dev):

1. Visit [https://prismor.dev](https://prismor.dev)
2. **Sign up** for a free account
3. Navigate to your dashboard
4. **Generate an API Key**
5. Copy your API key

### Setting Up Your API Key

Once you have your API key, set it as an environment variable:

```bash
export PRISMOR_API_KEY=your_api_key_here
```

To make this permanent, add it to your shell configuration file (`~/.bashrc`, `~/.zshrc`, etc.):

```bash
echo 'export PRISMOR_API_KEY=your_api_key_here' >> ~/.zshrc
source ~/.zshrc
```

### Private Repositories

To scan **private repositories**, you need to integrate your GitHub account:

1. Go to [Prismor.dev](https://prismor.dev)
2. Navigate to **Settings** or **Integrations**
3. **Connect your GitHub account**
4. Authorize Prismor to access your private repositories

This allows Prismor to securely access and scan your private repositories.

## Usage

### Basic Syntax

```bash
prismor --repo <repository> [scan-type]
```

**Note**: The `--scan` flag is used to enable vulnerability scanning, while `--repo` specifies the repository to scan.

### Repository Format

Prismor CLI supports multiple GitHub repository URL formats for maximum flexibility:

#### 1. **Username/Repository format** (recommended):
```bash
prismor --repo Ar9av/trychai-web-revamped --fullscan
```

#### 2. **HTTPS URLs**:
```bash
prismor --repo https://github.com/Ar9av/trychai-web-revamped --fullscan
prismor --repo https://www.github.com/Ar9av/trychai-web-revamped --fullscan
prismor --repo https://github.com/Ar9av/trychai-web-revamped.git --fullscan
```

#### 3. **HTTP URLs**:
```bash
prismor --repo http://github.com/Ar9av/trychai-web-revamped --fullscan
prismor --repo http://www.github.com/Ar9av/trychai-web-revamped --fullscan
```

#### 4. **Bare domain formats**:
```bash
prismor --repo github.com/Ar9av/trychai-web-revamped --fullscan
prismor --repo www.github.com/Ar9av/trychai-web-revamped --fullscan
```

#### 5. **SSH format**:
```bash
prismor --repo git@github.com:Ar9av/trychai-web-revamped.git --fullscan
```

#### 6. **URLs with paths and fragments**:
```bash
prismor --repo https://github.com/Ar9av/trychai-web-revamped/tree/main --fullscan
prismor --repo https://github.com/Ar9av/trychai-web-revamped/blob/main/file.py --fullscan
prismor --repo https://github.com/Ar9av/trychai-web-revamped#branch --fullscan
```

**All formats are automatically parsed and normalized to extract the `user/repo_name` format for processing.**

### Smart URL Parsing

Prismor CLI features intelligent GitHub URL parsing that automatically:

- ✅ **Detects and extracts** repository information from any supported format
- ✅ **Handles edge cases** like trailing slashes, `.git` suffixes, and branch references
- ✅ **Validates input** to ensure it's a valid GitHub repository
- ✅ **Provides clear error messages** for unsupported formats
- ✅ **Supports special characters** in repository names (hyphens, underscores, numbers)

**Examples of what gets automatically parsed:**
```bash
# All of these resolve to "facebook/react":
prismor --repo facebook/react --scan
prismor --repo https://github.com/facebook/react --scan
prismor --repo git@github.com:facebook/react.git --scan
prismor --repo github.com/facebook/react --scan
prismor --repo https://github.com/facebook/react/tree/main --scan
```

### Scan Types

#### 1. Vulnerability Scanning (scan)

Scan for security vulnerabilities in your dependencies and code:

```bash
prismor --repo myrepository --scan
```

**Note**: Vulnerability scans now run asynchronously for large repositories. The CLI will wait for completion automatically, but you can also use `prismor start-scan` to get a job ID and check status separately.

#### 2. Secret Detection

Detect exposed secrets, API keys, passwords, and other sensitive information:

```bash
prismor --repo myrepository --detect-secret
```

#### 3. SBOM Generation

Generate a Software Bill of Materials for your repository:

```bash
prismor --repo myrepository --sbom
```

#### 4. Full Scan

Run all security checks (scan + Secret Detection + SBOM):

```bash
prismor --repo myrepository --fullscan
```

### Multiple Scan Types

You can combine multiple scan types:

```bash
prismor --repo myrepository --scan --detect-secret
```

### JSON Output

Get results in JSON format for automation and integration:

```bash
prismor --repo myrepository --fullscan --json
```

## Examples

### Example 1: Quick Vulnerability Scan (Username/Repo format)

```bash
prismor --repo facebook/react --scan
```

### Example 2: Comprehensive Security Audit (HTTPS URL)

```bash
prismor --repo https://github.com/microsoft/vscode --fullscan
```

### Example 3: Secret Detection with SSH URL

```bash
prismor --repo git@github.com:openai/gpt-3.git --detect-secret
```

### Example 4: SBOM Generation with Bare Domain

```bash
prismor --repo github.com/kubernetes/kubernetes --sbom --json > sbom-results.json
```

### Example 5: Full Scan with Branch Reference

```bash
prismor --repo https://github.com/tensorflow/tensorflow/tree/v2.13.0 --fullscan
```

### Example 6: Multiple Scan Types with Different URL Formats

```bash
# Using HTTPS URL
prismor --repo https://github.com/pytorch/pytorch --scan --sbom

# Using SSH URL
prismor --repo git@github.com:nodejs/node.git --detect-secret --sbom

# Using bare domain
prismor --repo www.github.com/vercel/next.js --fullscan
```

### Example 7: Save Results to File

```bash
# Save full scan results to JSON file
prismor --repo username/repo --fullscan --output results.json

# Save vulnerability scan with specific branch
prismor --repo username/repo --scan --branch develop --output vuln-scan.json

# Quiet mode with file output (no console output)
prismor --repo username/repo --sbom --output sbom.json --quiet
```

### Example 8: CI/CD Integration

```bash
# Minimal output for CI/CD pipelines
prismor --repo $REPO_NAME --scan --quiet --json > scan-results.json

# Exit with error code if scan fails
prismor --repo username/repo --fullscan --quiet || exit 1

# Save results and continue pipeline
prismor --repo username/repo --scan --output scan.json --quiet && \
  echo "Scan completed, results saved to scan.json"
```

### Example 7: Async Scan with Status Checking

```bash
# Start a scan and get job ID
prismor start-scan username/repo --branch main

# Check scan status (use job ID from previous command)
prismor scan-status <job_id>

# Check status with JSON output
prismor scan-status <job_id> --json
```

## Additional Commands

### Start Async Vulnerability Scan

Start a vulnerability scan asynchronously and get a job ID for status checking:

```bash
prismor start-scan username/repo
prismor start-scan username/repo --branch develop
prismor start-scan username/repo --token ghp_xxxxx
```

**Note**: Requires GitHub token. Set `GITHUB_TOKEN` environment variable or use `--token` option.

### Check Scan Status

Check the status of a running or completed vulnerability scan:

```bash
prismor scan-status <job_id>
prismor scan-status <job_id> --json
```

**Status Response Includes**:
- Job status (running/completed/failed)
- Repository and branch information
- Results URLs (public and presigned)
- Vulnerability summary with severity breakdown
- Scan date and duration

**Example Output**:
```
============================================================
  Scan Status
============================================================

Job ID: abc123def456...

Status: completed

Repository:
  https://github.com/username/repo

Branch:
  main

Vulnerability Summary:
  Total Vulnerabilities: 15
  Total Targets Scanned: 3

  Severity Breakdown:
    CRITICAL: 2
    HIGH: 5
    MEDIUM: 6
    LOW: 2

Results URL:
  https://prismor-sbom-public-dev.s3.amazonaws.com/...
```

### Check Configuration

View your current Prismor CLI configuration:

```bash
prismor config
```

### Version Information

Display the version of Prismor CLI:

```bash
prismor version
```

Or:

```bash
prismor --version
```

### Help

Get help and see all available options:

```bash
prismor --help
```

## Output

Prismor CLI provides clear, colorful output with:

- ✓ Success indicators
- ✗ Error messages
- ℹ Information updates
- ⚠ Warnings
- Detailed scan results including:
  - Repository information
  - Vulnerability counts
  - Secret detection findings
  - SBOM artifact counts
  - Download links for detailed reports

## Full Analysis & Dashboarding

For comprehensive analysis and visualization of your scan results, visit the **[Prismor Dashboard](https://prismor.dev)**:

### Features Available on Prismor.dev:
- 📊 **Interactive Dashboards** - Visualize security trends and metrics
- 📈 **Historical Analysis** - Track vulnerabilities over time
- 🎯 **Detailed Reports** - In-depth analysis of all findings
- 🔔 **Alerts & Notifications** - Get notified of critical issues
- 👥 **Team Collaboration** - Share reports with your team
- 🔄 **CI/CD Integration** - Automate scans in your pipeline
- 📁 **Repository Management** - Manage multiple repositories in one place

### Accessing Full Reports:

After running a scan with the CLI, you can:

1. Visit [https://prismor.dev](https://prismor.dev)
2. Log into your dashboard
3. View all your scan results with rich visualizations
4. Export reports in various formats
5. Set up automated scanning schedules

The CLI provides quick results in your terminal, while the web dashboard offers comprehensive analysis and long-term security monitoring.

## API Information

Prismor CLI communicates with the Prismor API at `https://api.prismor.dev`. The CLI handles:

- Authentication via API key
- Request formatting
- Error handling
- Response parsing
- Result presentation

## Advanced Usage

### Save Results to File

Save scan results to a JSON file for later analysis:

```bash
prismor --repo username/repo --fullscan --output results.json
```

### Quiet Mode

Run scans with minimal output (useful for CI/CD pipelines):

```bash
prismor --repo username/repo --scan --quiet
```

### Combining Options

Combine multiple options for customized workflows:

```bash
# Scan specific branch and save to file
prismor --repo username/repo --scan --branch develop --output scan-results.json

# Quiet mode with JSON output
prismor --repo username/repo --fullscan --quiet --json

# Save results without console output
prismor --repo username/repo --sbom --output sbom.json --quiet
```

## Troubleshooting

### API Key Not Set

**Error:**
```
✗ PRISMOR_API_KEY environment variable is not set.
```

**Solution:**
```bash
# Set temporarily (current session only)
export PRISMOR_API_KEY=your_api_key_here

# Set permanently (add to ~/.bashrc or ~/.zshrc)
echo 'export PRISMOR_API_KEY=your_api_key_here' >> ~/.zshrc
source ~/.zshrc
```

**Get your API key:**
1. Visit [https://prismor.dev/cli](https://prismor.dev/cli)
2. Sign up for a free account
3. Generate an API key from your dashboard

---

### Invalid Repository Format

**Error:**
```
✗ Unrecognized repository format
```

**Supported formats:**
- ✅ `username/repository` (recommended)
- ✅ `https://github.com/username/repository`
- ✅ `https://www.github.com/username/repository`
- ✅ `http://github.com/username/repository`
- ✅ `http://www.github.com/username/repository`
- ✅ `github.com/username/repository`
- ✅ `www.github.com/username/repository`
- ✅ `git@github.com:username/repository.git`
- ✅ `https://github.com/username/repository/tree/branch`
- ✅ `https://github.com/username/repository/blob/branch/file`

**Not supported:**
- ❌ Non-GitHub URLs (GitLab, Bitbucket, etc.)
- ❌ Invalid URL formats
- ❌ Empty or malformed repository names
- ❌ Repository names with invalid characters

**Valid characters:**
- Alphanumeric (a-z, A-Z, 0-9)
- Hyphens (-)
- Underscores (_)
- Dots (.)
- Cannot start or end with special characters

---

### Connection Issues

**Error:**
```
✗ Failed to connect to Prismor API
```

**Solutions:**

1. **Check Internet Connection**
   ```bash
   ping prismor.dev
   ```

2. **Verify API Endpoint**
   ```bash
   curl -I https://prismor.dev
   ```

3. **Test API Key**
   ```bash
   prismor config
   ```

4. **Check Firewall/Proxy**
   - Ensure your firewall allows HTTPS connections
   - Configure proxy if needed:
     ```bash
     export HTTPS_PROXY=http://proxy.example.com:8080
     ```

5. **Retry with Automatic Retries**
   - The CLI automatically retries failed requests 3 times with exponential backoff
   - If issues persist, check your network configuration

---

### Timeout Issues

**Error:**
```
✗ Request timed out
```

**Solutions:**

1. **Large Repositories**
   - Vulnerability scans can take up to 10 minutes for large repositories
   - The CLI will wait automatically
   - Use `--quiet` mode to reduce output during long scans

2. **Network Latency**
   - Check your internet speed
   - Try again during off-peak hours
   - Consider using a wired connection

3. **Check Scan Status**
   ```bash
   # Start scan asynchronously
   prismor start-scan username/repo
   
   # Check status later
   prismor scan-status <job_id>
   ```

---

### Private Repository Access

**Error:**
```
✗ GitHub integration required
```

**Solution:**
1. Visit [https://prismor.dev/dashboard](https://prismor.dev/dashboard)
2. Navigate to Settings → Integrations
3. Connect your GitHub account
4. Authorize Prismor to access private repositories
5. Try scanning again

---

### Invalid Characters in Repository Name

**Error:**
```
✗ Invalid Username: 'user@name'. Must contain only alphanumeric characters...
```

**Solution:**
- Ensure repository name follows GitHub naming conventions
- Remove special characters like `@`, `#`, `$`, etc.
- Valid example: `username/my-repo-name`
- Invalid example: `user@name/repo#123`

---

### Rate Limiting

**Error:**
```
✗ API error: Rate limit exceeded
```

**Solution:**
1. Wait a few minutes before retrying
2. Check your account limits at [prismor.dev/dashboard](https://prismor.dev/dashboard)
3. Upgrade your plan if needed for higher limits

---

### Getting Help

If you're still experiencing issues:

1. **Check Configuration**
   ```bash
   prismor config
   ```

2. **View Account Status**
   ```bash
   prismor status
   ```

3. **Enable Verbose Output**
   - Remove `--quiet` flag to see detailed error messages

4. **Contact Support**
   - Visit [https://prismor.dev](https://prismor.dev)
   - Check documentation at [https://docs.prismor.dev](https://docs.prismor.dev)
   - Report issues at [GitHub Issues](https://github.com/PrismorSec/prismor-cli/issues)

## Development

### Local Installation

For development, clone the repository and install in editable mode:

```bash
git clone https://github.com/PrismorSec/prismor-cli.git
cd prismor-cli
pip install -e .
```

### Project Structure

```
prismor-cli/
├── prismor/
│   ├── __init__.py      # Package initialization
│   ├── cli.py           # CLI interface and commands
│   └── api.py           # API client and communication
├── setup.py             # Package configuration
├── requirements.txt     # Dependencies
└── README.md            # Documentation
```

## Requirements

- Python 3.7 or higher
- `click` >= 8.0.0
- `requests` >= 2.25.0

## License

MIT License - See LICENSE file for details

## Support

- **Website**: [https://prismor.dev](https://prismor.dev)
- **Dashboard**: [https://prismor.dev](https://prismor.dev) (Sign up for full features)
- **Documentation**: [https://docs.prismor.dev](https://docs.prismor.dev)
- **Issues**: [https://github.com/PrismorSec/prismor-cli/issues](https://github.com/prismor/prismor-cli/issues)

### Need Help?

1. Visit [Prismor.dev](https://prismor.dev) for full documentation and support
2. Check the dashboard for detailed scan results and analysis
3. Join our community for questions and discussions

## Contributing

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

---

Made with ❤️ by Prismor