@redpillsec/cli/README.md

RedPill Security CLI - OpenAPI security scanner that reveals vulnerabilities in your API specifications

<div align="center">
  <h1>🔴 RedPill Security CLI</h1>
  <p><strong>See how deep the vulnerability hole goes</strong></p>
  
  [![npm version](https://badge.fury.io/js/%40redpillsec%2Fcli.svg)](https://badge.fury.io/js/%40redpillsec%2Fcli)
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.18.0-brightgreen.svg)](https://nodejs.org/)
</div>

## 🚀 Quick Start

```bash
# Install globally
npm install -g @redpillsec/cli

# Scan your OpenAPI specification
redpill scan openapi api.yaml

# Get help
redpill --help
```

## 📖 About

RedPill Security CLI is a powerful OpenAPI security scanner that reveals vulnerabilities in your API specifications. Take the red pill and see the security issues you didn't know existed.

### 🎯 Features

- **OpenAPI Security Scanning**: Comprehensive analysis of OpenAPI/Swagger specifications  
- **Multiple Output Formats**: Text, JSON, CSV, and Markdown reports
- **Configurable Rules**: Customize security rules via configuration files
- **CI/CD Ready**: Perfect for automated security testing in pipelines
- **Detailed Reports**: Clear explanations of vulnerabilities and recommendations

## 🔧 Installation

### Global Installation (Recommended)
```bash
npm install -g @redpillsec/cli
```

### Local Installation
```bash
npm install --save-dev @redpillsec/cli
```

## 📋 Usage

### Basic Scanning
```bash
# Scan a single OpenAPI file
redpill scan openapi api.yaml

# Scan with JSON output
redpill scan openapi api.yaml --format json

# Save results to file
redpill scan openapi api.yaml --output results.json
```

### Advanced Options
```bash
# Use custom configuration
redpill scan openapi api.yaml --config custom-rules.json

# Verbose output
redpill scan openapi api.yaml --verbose

# Quiet mode (errors only)
redpill scan openapi api.yaml --quiet
```

### Configuration Management
```bash
# Create default configuration file
redpill init-config

# Create config with custom path
redpill init-config my-config.json
```

## ⚙️ Configuration

Create a `redpill.config.json` file to customize security rules:

```json
{
  "rules": {
    "security-definition-required": true,
    "no-http-basic": true,
    "security-schemes-defined": true,
    "no-secrets-in-url": true,
    "https-required": true
  },
  "output": {
    "format": "text",
    "verbose": false
  }
}
```

## 📊 Output Formats

### Text (Default)
Human-readable format perfect for terminal output and quick reviews.

### JSON
```bash
redpill scan openapi api.yaml --format json
```
Machine-readable format ideal for CI/CD integration and automated processing.

### CSV
```bash
redpill scan openapi api.yaml --format csv
```
Spreadsheet-compatible format for reporting and analysis.

### Markdown
```bash
redpill scan openapi api.yaml --format markdown
```
Documentation-friendly format for reports and wikis.

## 🔍 Security Rules

RedPill Security CLI checks for various OpenAPI security issues:

- **Missing Security Definitions**: APIs without proper security schemes
- **Weak Authentication**: HTTP Basic auth and other weak methods
- **Insecure Protocols**: HTTP instead of HTTPS
- **Exposed Secrets**: API keys and tokens in URLs
- **Missing Security Requirements**: Endpoints without security enforcement
- **And many more...**

## 🛠️ CI/CD Integration

### GitHub Actions
```yaml
- name: Install RedPill Security CLI
  run: npm install -g @redpillsec/cli

- name: Scan OpenAPI Spec
  run: redpill scan openapi api.yaml --format json --output security-report.json
```

### Jenkins
```groovy
sh 'npm install -g @redpillsec/cli'
sh 'redpill scan openapi api.yaml --format json --output security-report.json'
```

## 📚 Examples

Check out our [examples directory](https://github.com/redpillsec/cli/tree/main/examples) for:
- Sample OpenAPI specifications
- Configuration examples
- CI/CD pipeline templates
- Output format samples

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 💬 Support

- 📧 Email: [support@redpillsec.io](mailto:support@redpillsec.io)
- 🌐 Website: [redpillsec.io](https://redpillsec.io)
- 🐛 Issues: [GitHub Issues](https://github.com/redpillsec/cli/issues)

## 🗺️ Roadmap

- 🔜 AI-powered vulnerability analysis
- 🔜 OWASP API Top 10 scanner
- 🔜 Real-time API monitoring
- 🔜 Integration with popular API gateways
- 🔜 Custom rule development framework

---

<div align="center">
  <p><strong>Take the red pill. See the vulnerabilities. Fix them. 🔴</strong></p>
  <p>Made with ❤️ by the RedPill Security team</p>
</div>