🛡️ Kiro AntiScam

Asistente de WhatsApp que detecta estafas en segundos

⚠️ Los veredictos son orientativos, no asesoramiento bancario, legal ni de seguridad.

📋 Tabla de Contenidos

Arquitectura
Estructura del Repo
Backend: Bot de WhatsApp
Frontend: Landing Page
Deploy en AWS
Variables de Entorno
Seguridad y Privacidad
Documentación
Equipo

Arquitectura

flowchart LR
    U[📱 Usuario WhatsApp] -->|Envía mensaje| K[Kapso API]
    K -->|Webhook POST| GW[AWS API Gateway]
    GW -->|Autentica firma| WH[Lambda Webhook]
    WH -->|Pseudonimiza + Redacta| SQS[SQS Queue]
    SQS -->|Consume| LP[Lambda Processor]
    LP -->|Rules + VT + RAG + Bedrock| AP[Analysis Pipeline]
    AP -->|Veredicto| LP
    LP -->|Responde| K
    K -->|Resultado| U

    subgraph AWS Cloud
        GW
        WH
        SQS
        LP
        AP
        DDB[(DynamoDB<br/>Consent + Idempotencia)]
        SM[(Secrets Manager)]
        CW[(CloudWatch<br/>Logs + Alarms)]
    end

    WH -.-> DDB
    LP -.-> DDB
    LP -.-> SM
    LP -.-> CW

WhatsApp ──→ Kapso ──→ API Gateway ──→ LambdaWebhook ──→ SQS ──→ LambdaProcessor ──→ Kapso ──→ WhatsApp
                               │                                              │
                               │                                              ▼
                               │                                    AnalysisPipeline
                               │                                   ├── Reglas rápidas
                               │                                   ├── VirusTotal
                               │                                   ├── RAG (casos históricos)
                               │                                   └── Bedrock (Claude)
                               │
                          DynamoDB (consentimiento, idempotencia)
                          Secrets Manager (API keys, HMAC secrets)
                          CloudWatch (logs, alarms, budgets)

Flujo

Usuario reenvía un mensaje sospechoso al número de WhatsApp del bot
Kapso recibe el mensaje y dispara un webhook
LambdaWebhook autentica la firma, seudonimiza al usuario, redacta datos sensibles y encola en SQS
LambdaProcessor consume de SQS, ejecuta el pipeline de análisis y responde por Kapso
El usuario recibe un veredicto: 🚨 estafa / ⚠️ cuidado / ✅ parece seguro

Stack tecnológico

Componente	Tecnología
Backend	TypeScript, Node.js 18.18+
Cloud	AWS (API Gateway, Lambda, SQS/DLQ, DynamoDB, Secrets Manager, KMS, CloudWatch)
Infraestructura	AWS CDK TypeScript
WhatsApp Gateway	Kapso API
Análisis	Reglas heurísticas + VirusTotal + AWS Bedrock (Claude Sonnet 4)
Testing	Vitest
Frontend	Next.js 14 (App Router), TypeScript, Tailwind CSS
Package manager	pnpm
Despliegue frontend	Vercel-ready

Estructura del Repo

kiro-antiscam/
├── src/                          # Backend — bot de WhatsApp
│   ├── agent/                    # Agentes de análisis (LLM + tools)
│   │   ├── analyze-with-agent.ts # Agente de análisis de estafas
│   │   ├── conversation-prompt.ts # Prompt para agente conversacional
│   │   ├── create-conversation-agent.ts # Agente de conversación
│   │   ├── create-conversation-service.ts # Servicio conversacional
│   │   ├── create-analysis-agent.ts  # Factory del agente de análisis
│   │   ├── system-prompt.ts      # System prompt del bot
│   │   ├── model/                # Proveedores de modelo (Bedrock)
│   │   └── tools/                # Tools del agente (URL reputation, casos, analyze-scam)
│   ├── analysis/                 # Pipeline de detección
│   ├── detection/                # Reglas rápidas de detección
│   ├── domain/                   # Modelos de dominio y tipos
│   ├── kapso/                    # Integración con Kapso API (auth, client, parser, QR)
│   ├── lambda/                   # Handlers de Lambda (webhook, processor)
│   ├── messaging/                # Normalización, consentimiento, redacción, responder
│   ├── ports/                    # Interfaces de puertos (análisis, redacción, URL, conversación)
│   ├── queue/                    # SQS publisher, idempotencia
│   ├── reputation/               # VirusTotal y cache de reputación
│   ├── known-cases/              # RAG de casos históricos
│   └── url/                      # Extracción, fetch seguro, SSRF protection
├── landing/                      # Frontend — landing page (Next.js)
│   ├── app/                      # App Router pages
│   ├── components/               # Componentes UI (Hero, HowItWorks, TryIt, etc.)
│   └── lib/                      # Config
├── infra/                        # AWS CDK (definición completa de infraestructura)
├── scripts/                      # Scripts de prueba y deploy
├── test/                         # Tests unitarios (Vitest)
├── docs/                         # Documentación adicional (SDD, verify-before-deploy)
├── .kiro/                        # Configuración Kiro hackathon
├── .env.example                  # Variables de entorno de ejemplo
├── pnpm-workspace.yaml           # Workspace pnpm
├── PRD.md                        # Product Requirements Document
├── SITEMAP.md                    # Mapa de arquitectura y componentes
├── TASKS.md                      # Desglose de tareas del proyecto
└── UBIQUITOUS_LANGUAGE.md        # Glosario de dominio ubicuo (DDD)

Backend: Bot de WhatsApp

Requisitos

Node.js 18.18+ y pnpm
[Opcional] Cuenta de AWS + AWS CLI configurado para deploy

Instalación y pruebas (local, no requiere AWS)

pnpm install
pnpm run build      # Compila TypeScript (strict mode)
pnpm test           # Tests unitarios

Scripts disponibles

Script	Propósito
`scripts/get-qr.sh`	Obtener QR para conectar WhatsApp
`scripts/whatsapp-send.sh`	Enviar mensaje de prueba
`scripts/webhook-with-url.sh`	Simular webhook con URL sospechosa
`scripts/set-secrets.sh`	Cargar secrets en AWS Secrets Manager
`scripts/webhook-consent.sh`	Simular flujo de consentimiento
`scripts/webhook-unprocessable.sh`	Simular mensaje no procesable

Frontend: Landing Page

Landing page del proyecto, construida con Next.js 14, App Router, TypeScript y Tailwind CSS. Mobile-first y accesible con componentes: Hero, HowItWorks, Steps, TryIt, Privacy, Footer, WhatsAppQR.

Inicio rápido

cd landing
pnpm install
pnpm dev            # http://localhost:3000

Build y despliegue

pnpm build          # Producción
pnpm start          # Servir build

Lista para deploy en Vercel con zero config.

Deploy en AWS

cd infra
pnpm install
npx cdk bootstrap                          # Solo la primera vez por cuenta/región
npx cdk deploy AntiScamBotStack \
  -c antiscambot:enableRoutingToken=true \
  -c antiscambot:kapsoPhoneNumberId=<PHONE_NUMBER_ID>

Post-deploy

# Cargar secrets reales
export KAPSO_WEBHOOK_SECRET_VALUE="..."
export USER_ID_HMAC_SECRET_VALUE="$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")"
export KAPSO_API_KEY_VALUE="..."
./scripts/set-secrets.sh

# Obtener URL del webhook
./scripts/get-webhook-url.sh

Luego en el panel de Kapso: crear un webhook tipo Kapso (events) con evento Message received y pegar la URL.

Detalle completo en infra/README.md.

Variables de Entorno

Que aporta el desarrollador (valores reales, nunca al repo)

Variable	De dónde sale
`KAPSO_API_KEY`	Panel de Kapso → Integrations → API keys
`KAPSO_PHONE_NUMBER_ID`	ID del número conectado en Kapso
`KAPSO_WEBHOOK_SECRET`	Secret key del webhook en Kapso
`USER_ID_HMAC_SECRET`	`node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`

Con default (no requiere tocar)

Variable	Default
`KAPSO_API_BASE_URL`	`https://api.kapso.ai/meta/whatsapp/v24.0`
`KAPSO_SIGNATURE_HEADER`	`x-webhook-signature`
`MESSAGE_MAX_LENGTH`	`4096`
`DEFAULT_LOCALE`	`es`
`CONSENT_TTL_DAYS`	`30`
`LOG_LEVEL`	`info`

Las provee el deploy (CDK)

AWS_REGION, SQS_QUEUE_URL, CONSENT_TABLE_NAME, *_ARN de secretos, ENABLE_ROUTING_TOKEN, ROUTING_TOKEN_KMS_KEY_ID.

Seguridad y Privacidad

Redacción determinista de datos sensibles (OTP, tarjetas, CBU, documentos) en el webhook, antes de SQS, logs o persistencia
El teléfono nunca se guarda en claro: se usa userId = HMAC-SHA256 del número
Webhook autenticado por firma HMAC, verificada en tiempo constante
Routing token cifrado con KMS (opcional)
Consentimiento explícito antes de analizar; datos con TTL en DynamoDB
Secretos en AWS Secrets Manager; IAM de mínimo privilegio

Documentación

Archivo	Contenido
`PRD.md`	Requisitos del producto, user stories, decisiones técnicas
`SITEMAP.md`	Mapa de arquitectura, endpoints, flujos, diagramas
`TASKS.md`	Desglose de tareas del proyecto
`UBIQUITOUS_LANGUAGE.md`	Glosario de dominio ubicuo (DDD)
`docs/sdd/`	SDD — Spec-Driven Development artifacts
`docs/verify-before-deploy.md`	Checklist de verificación pre-deploy
`infra/README.md`	Documentación detallada del deploy
`scripts/README.md`	Scripts de prueba y E2E
`landing/README.md`	Documentación de la landing page

👥 Equipo

Rol	Integrante
🔧 Kapso / Infra / Agent pipeline
🕵️ Análisis / Detección / URLs
🎨 Landing page / Frontend
🚀 Fork y mantenimiento

📜 Licencia

MIT — Hecho con 💙 para la comunidad LATAM durante el hackathon AWS × Código Facilito.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

🛡️ Kiro AntiScam

📋 Tabla de Contenidos

Arquitectura

Flujo

Stack tecnológico

Estructura del Repo

Backend: Bot de WhatsApp

Requisitos

Instalación y pruebas (local, no requiere AWS)

Scripts disponibles

Frontend: Landing Page

Inicio rápido

Build y despliegue

Deploy en AWS

Post-deploy

Variables de Entorno

Que aporta el desarrollador (valores reales, nunca al repo)

Con default (no requiere tocar)

Las provee el deploy (CDK)

Seguridad y Privacidad

Documentación

👥 Equipo

📜 Licencia

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.kiro		.kiro
.vscode		.vscode
docs		docs
infra		infra
landing		landing
scripts		scripts
src		src
test		test
.env.example		.env.example
.gitignore		.gitignore
PRD.md		PRD.md
README.md		README.md
SITEMAP.md		SITEMAP.md
TASKS.md		TASKS.md
UBIQUITOUS_LANGUAGE.md		UBIQUITOUS_LANGUAGE.md
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

🛡️ Kiro AntiScam

📋 Tabla de Contenidos

Arquitectura

Flujo

Stack tecnológico

Estructura del Repo

Backend: Bot de WhatsApp

Requisitos

Instalación y pruebas (local, no requiere AWS)

Scripts disponibles

Frontend: Landing Page

Inicio rápido

Build y despliegue

Deploy en AWS

Post-deploy

Variables de Entorno

Que aporta el desarrollador (valores reales, nunca al repo)

Con default (no requiere tocar)

Las provee el deploy (CDK)

Seguridad y Privacidad

Documentación

👥 Equipo

📜 Licencia

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages