npm package: @ideascol/xsecurity-cli
Description: this tools for audit swagger definition
Author: ideascol
Latest version: 0.0.1

# @ideascol/xsecurity-cli

![Security](https://img.shields.io/badge/Security-Testing-red)
![Version](https://img.shields.io/badge/version-0.0.1-blue)
![License](https://img.shields.io/badge/license-MIT-green)

## 🛡️ API Security Testing Tool

Una potente herramienta de línea de comandos para realizar auditorías de seguridad en APIs definidas con Swagger/OpenAPI. Identifica vulnerabilidades comunes como SSRF, inyección SQL, exposición de errores, bypass de autenticación y operaciones de escritura no autorizadas.

### ✨ Características

- **Análisis completo de seguridad**: Detecta vulnerabilidades en endpoints de API basados en definiciones Swagger/OpenAPI
- **Múltiples niveles de prueba**: Configura la intensidad de las pruebas (bajo, medio, alto)
- **Información detallada del objetivo**: Recopila datos sobre el servidor analizado (hostname, IP, plataforma, etc.)
- **Resumen de pruebas**: Proporciona estadísticas detalladas sobre las pruebas realizadas
- **Recomendaciones**: Ofrece sugerencias para mitigar las vulnerabilidades encontradas

## 🚀 Instalación

```bash
npm install -g @ideascol/xsecurity-cli
```

## 🔍 Uso

### Como herramienta CLI

```bash
# Análisis básico de una API
xsecurity-cli analyze-swagger --url="https://example.com/api-docs" --baseUrl="https://example.com" --testLevel="medium"

# Con autenticación (si es necesario)
xsecurity-cli analyze-swagger --url="https://example.com/api-docs" --baseUrl="https://example.com" --testLevel="high" --auth="Bearer your-token-here"
```

### Niveles de prueba

- **low**: Pruebas básicas, principalmente no intrusivas
- **medium**: Equilibrio entre detección y seguridad
- **high**: Pruebas exhaustivas, incluyendo payloads potencialmente disruptivos

### Como biblioteca

```typescript
import { analyzeSwagger } from '@ideascol/xsecurity-cli';

async function runSecurityTest() {
  const result = await analyzeSwagger(
    'https://example.com/api-docs',
    'https://example.com',
    'medium',
    'Bearer your-token-here' // opcional
  );
  
  console.log(JSON.stringify(result, null, 2));
}

runSecurityTest();
```

## 📊 Resultados

La herramienta genera un informe detallado en formato JSON que incluye:

- **Información del objetivo**: Detalles sobre el servidor analizado
- **Resumen de pruebas**: Estadísticas sobre las pruebas realizadas
- **Vulnerabilidades**: Lista detallada de problemas encontrados
- **Recomendaciones**: Sugerencias para mejorar la seguridad

### Ejemplo de resultado

```json
{
  "swaggerUrl": "https://example.com/api-docs",
  "analysisTimestamp": "2025-03-14T20:00:00.000Z",
  "targetInformation": {
    "hostname": "example-server",
    "ip": "203.0.113.1",
    "platform": "linux",
    "architecture": "x64",
    "serverType": "Nginx"
  },
  "summary": {
    "totalEndpoints": 25,
    "totalVulnerabilities": 3,
    "riskLevel": "medium",
    "securityTestsExecuted": {
      "description": "Executed 75 security tests in 25 endpoints of the API",
      "testsByCategory": {
        "ssrf": { "count": 25, "description": "Tests for Server Side Request Forgery vulnerabilities" },
        "sqlInjection": { "count": 15, "description": "Tests for SQL Injection vulnerabilities" },
        "errorExposure": { "count": 25, "description": "Tests for Error Information Exposure" },
        "authBypass": { "count": 5, "description": "Tests for Authentication Bypass" },
        "writeOperations": { "count": 5, "description": "Tests for unauthorized write operations" }
      },
      "totalTests": 75
    }
  },
  "vulnerabilities": [
    {
      "endpoint": "/api/users",
      "method": "GET",
      "issue": "Authentication Bypass",
      "severity": "high",
      "recommendation": "Implementar autenticación en todos los endpoints sensibles"
    }
  ]
}
```

## 🔧 Desarrollo

```bash
# Clonar el repositorio
git clone https://github.com/ideascol/xsecurity-cli.git
cd xsecurity-cli

# Instalar dependencias
npm install

# Compilar
npm run build

# Ejecutar localmente
npm start -- analyze-swagger --url="http://localhost:3000/api.json" --baseUrl="http://localhost:3000" --testLevel="medium"

# Ejecutar pruebas
npm test
```

## 📝 Licencia

Este proyecto está licenciado bajo la Licencia MIT - vea el archivo [LICENSE](LICENSE) para más detalles.

## 🤝 Contribuciones

Las contribuciones son bienvenidas. Por favor, abra un issue primero para discutir lo que le gustaría cambiar.

---

Desarrollado por [ideascol](mailto:ideas.col.apps@gmail.com)