prismor 0.1.2__py3-none-any.whl → 1.1.1__py3-none-any.whl

prismor-1.1.1.dist-info/METADATA

@@ -0,0 +1,744 @@
+Metadata-Version: 2.4
+Name: prismor
+Version: 1.1.1
+Summary: A CLI tool for scanning GitHub repositories for vulnerabilities, secrets, and generating SBOMs
+Home-page: https://github.com/PrismorSec/prismor-cli
+Author: Prismor
+Author-email: support@prismor.dev
+Project-URL: Bug Reports, https://github.com/PrismorSec/prismor-cli/issues
+Project-URL: Source, https://github.com/PrismorSec/prismor-cli
+Project-URL: Documentation, https://docs.prismor.dev
+Project-URL: Homepage, https://prismor.dev
+Keywords: security scanning vulnerability sbom secrets github
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0.0
+Requires-Dist: requests>=2.25.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# 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