Nexus - AI Task Orchestrator

41-security-scope-audit
Procedimiento: Auditor├¡a de Scopes y Permisos

Seguridad
1 plugin(s)
Titulo
Descripcion
Contenido Markdown
7966 caracteres
# Procedimiento: Auditor├¡a de Scopes y Permisos

## Metadata
- **ID**: PROC-41
- **Frecuencia**: Trimestral, o despu├®s de a├▒adir nuevas tools
- **Duraci├│n estimada**: 1-2 horas
- **Requiere**: Acceso al c├│digo, conocimiento de OAuth scopes
- **Dependencias**: PROC-06 (si hay tools nuevas)
- **Bloquea**: Nada directamente (informativo)

## Objetivo

Verificar que los scopes OAuth est├ín correctamente asignados a cada tool MCP, siguiendo el principio de m├¡nimo privilegio.

## Scopes Disponibles

| Scope | Descripci├│n | Nivel |
|-------|-------------|-------|
| `dmi:catalog:read` | Leer cat├ílogo, productos, categor├¡as | Bajo |
| `dmi:pricing:read` | Leer precios espec├¡ficos de cliente | Medio |
| `dmi:orders:read` | Leer pedidos, facturas | Medio |
| `dmi:orders:write` | Crear/modificar pedidos | Alto |
| `dmi:support:read` | Leer tickets de soporte | Medio |
| `dmi:support:write` | Crear tickets de soporte | Alto |
| `dmi:sales:read` | Modo comercial (acceso a clientes) | Alto |
| `dmi:ai_feedback:read` | Leer feedback IA | Bajo |
| `dmi:ai_feedback:write` | Escribir feedback IA | Bajo |

## Checklist Ejecutable

### 1. Extraer mapping actual de scopes
```bash
cd src/src/BigCommerceApi

# Listar todas las tools y sus scopes
grep -rn "RequiredScope" Mcp/Tools/ --include="*.cs" \
  | grep "=>" \
  | sed 's/.*RequiredScope => "\([^"]*\)".*/\1/' \
  | sort | uniq -c | sort -rn
```
```bash
# Extraer tabla completa: Tool -> Scope
grep -rn "public string Name\|RequiredScope" Mcp/Tools/ --include="*.cs" \
  | paste - - \
  | awk -F: '{print $3}' \
  | sed 's/.*=> "\([^"]*\)".*=> "\([^"]*\)".*/\1,\2/'
```

Generar tabla:

| Tool | Scope Actual | Scope Esperado | OK |
|------|--------------|----------------|-----|
| products_search | | dmi:catalog:read | |
| pricing_get | | dmi:pricing:read | |
| orders_create | | dmi:orders:write | |
| ... | | | |

- [ ] Mapping extra├¡do

### 2. Verificar principio de m├¡nimo privilegio

Para cada tool, verificar:

| Pregunta | S├¡ | No |
|----------|----|----|
| ┬┐La tool solo lee datos? | ÔåÆ `:read` | ÔåÆ `:write` |
| ┬┐Accede a datos sensibles (precios, pedidos)? | ÔåÆ scope espec├¡fico | ÔåÆ `catalog:read` |
| ┬┐Modifica estado? | ÔåÆ `:write` | ÔåÆ `:read` |
| ┬┐Accede a datos de otros clientes? | ÔåÆ `sales:read` | ÔåÆ scope normal |

**Red flags:**
- Tool de lectura con scope `:write`
- Tool de cat├ílogo con scope de orders
- Tool sin validaci├│n de scope

### 3. Verificar implementaci├│n de scope check
```bash
# Verificar que McpToolInvoker verifica scopes
grep -A 20 "CheckScope\|RequiredScope" src/src/BigCommerceApi/Mcp/Infrastructure/McpToolInvoker.cs
```

Verificar que existe algo como:
```csharp
if (!userScopes.Contains(tool.RequiredScope))
{
    throw new McpToolException(403, $"Scope requerido: {tool.RequiredScope}");
}
```

- [ ] Scope check implementado correctamente

### 4. Verificar que tools peligrosas tienen scope correcto

**Tools de alto riesgo:**

| Tool | Scope Requerido | Raz├│n |
|------|-----------------|-------|
| `orders_create` | `dmi:orders:write` | Crea pedidos |
| `orders_delete` | `dmi:orders:write` | Elimina pedidos |
| `sales_customer_set_active` | `dmi:sales:read` | Cambia contexto de cliente |
| `support_incident_create` | `dmi:support:write` | Crea tickets |
```bash
# Verificar cada una
grep -A 5 'Name => "orders_create"' Mcp/Tools/Orders/*.cs
grep -A 5 'Name => "orders_delete"' Mcp/Tools/Orders/*.cs
grep -A 5 'Name => "sales_customer_set_active"' Mcp/Tools/Sales/*.cs
```

- [ ] Tools de alto riesgo tienen scopes correctos

### 5. Verificar que no hay bypass de scopes
```bash
# Buscar acceso directo a servicios sin pasar por scope check
grep -rn "InvokeAsync" Mcp/Tools/ --include="*.cs" -A 30 \
  | grep -v "RequiredScope"

# Buscar tools que no implementan IMcpTool correctamente
grep -L "RequiredScope" Mcp/Tools/**/*.cs
```

- [ ] No hay bypass de scopes

### 6. Auditar tokens/API keys existentes

Si hay acceso a la lista de API keys:
```sql
-- Verificar scopes asignados a API keys (si est├í en BD)
SELECT
    ApiKey,
    UserCode,
    Scopes,
    CreatedAt,
    LastUsedAt
FROM dbo.ApiKeys
ORDER BY LastUsedAt DESC;
```

Verificar:
- [ ] No hay API keys con todos los scopes (superuser)
- [ ] API keys de servicios tienen scopes m├¡nimos
- [ ] API keys no usadas en >90 d├¡as ÔåÆ considerar revocar

### 7. Documentar hallazgos

| # | Tool/Key | Problema | Severidad | Acci├│n |
|---|----------|----------|-----------|--------|
| 1 | | | Alta/Media/Baja | |
| 2 | | | | |

### 8. Crear tickets para correcciones

Para cada hallazgo:
```bash
# Ejemplo de fix: cambiar scope
# En ToolName.cs:
# public string RequiredScope => "dmi:orders:read"; // era :write
```

- [ ] Tickets creados para correcciones

## Matriz de Scopes por Dominio

### Referencia: Qu├® scope para qu├® operaci├│n

| Operaci├│n | Scope |
|-----------|-------|
| Buscar productos | `dmi:catalog:read` |
| Ver categor├¡as | `dmi:catalog:read` |
| Ver precios de cliente | `dmi:pricing:read` |
| Ver stock | `dmi:catalog:read` |
| Ver pedidos propios | `dmi:orders:read` |
| Crear pedido | `dmi:orders:write` |
| Modificar pedido | `dmi:orders:write` |
| Ver facturas | `dmi:orders:read` |
| Ver tickets soporte | `dmi:support:read` |
| Crear ticket | `dmi:support:write` |
| Buscar clientes (comercial) | `dmi:sales:read` |
| Operar como cliente | `dmi:sales:read` |

## Troubleshooting

| S├¡ntoma | Causa | Acci├│n |
|---------|-------|--------|
| Usuario recibe 403 | Falta scope en token | Verificar OAuth consent |
| Tool no aparece en tools/list | Scope no autorizado | Correcto (by design) |
| Scope demasiado amplio | Error de implementaci├│n | Corregir en c├│digo |

## Resultado

- **├ëxito**: Todos los scopes correctos, documentaci├│n actualizada
- **Parcial**: Hallazgos identificados, tickets creados
- **Fallo**: Problemas cr├¡ticos de seguridad ÔåÆ Escalar inmediatamente

## Mensaje de Finalizaci├│n

**IMPORTANTE - ACCI├ôN REQUERIDA AL FINALIZAR:**

Cuando hayas completado todos los pasos de este procedimiento, DEBES ejecutar el siguiente comando usando la herramienta Bash:

Ejecuta: `echo "====== PROCESO TERMINADO [$(date +%H%M%S)] ======" && echo "RESULTADO: X tools auditadas, Y hallazgos scopes, 0 criticos"`

Sustituye X e Y por los n├║meros reales.


---

## Output Estructurado (Nexus)

Al finalizar, el agente DEBE generar un bloque JSON con el siguiente formato para que Nexus pueda procesarlo automaticamente:

```json
{
  "result": "success",
  "summary": "Ejecucion de PROC-41 completada. [Descripcion breve de resultados]",
  "metrics": {
    "issues_found": 0,
    "issues_resolved": 0,
    "findings_total": 5, "findings_critical": 0,
    "custom": {
      "procedure_specific_metric": "value"
    }
  },
  "backlog_items": [
    {
      "title": "Titulo del item de seguimiento",
      "description": "Descripcion detallada si se requiere accion futura",
      "priority": "medium",
      "type": "improvement",
      "tags": ["proc-41"]
    }
  ],
  "next_steps": [
    "Accion recomendada 1",
    "Accion recomendada 2"
  ],
  "warnings": [
    "Advertencias encontradas durante la ejecucion"
  ]
}
```

**Campos requeridos:**
- `result`: `"success"` | `"partial"` | `"failed"`
- `summary`: Resumen ejecutivo en 1-3 lineas

**Metricas especificas de este procedure:**
- scopes_reviewed, scopes_excessive, recommendations

**Criterios de resultado:**
- `success`: Procedimiento completado sin errores criticos
- `partial`: Completado con algunos problemas menores o items pendientes
- `failed`: Error critico o no se pudo completar

## Historial de Auditor├¡as

| Fecha | Tools Auditadas | Hallazgos | Cr├¡ticos | Corregidos |
|-------|-----------------|-----------|----------|------------|
| | | | | |