ShieldOps AI

📋1. Overview#

📋١. نظرة عامة#

📋1. 概述#

📋1. Resumen#

🏗️2. System Architecture#

🏗️٢. بنية النظام#

🏗️2. 系统架构#

🏗️2. Arquitectura del Sistema#

ShieldOps follows a modular Flask Blueprint architecture with layered middleware: JWT auth → RBAC guard → module routing → AI assistance layer → data persistence → billing layer. Each module is independently deployable.

تتبع ShieldOps بنية معيارية من قوالب Flask مع وسيط طبقي: مصادقة JWT ← حارس RBAC ← توجيه الوحدات ← طبقة المساعدة بالذكاء الاصطناعي ← تخزين البيانات ← طبقة الفوترة. كل وحدة قابلة للنشر بشكل مستقل.

ShieldOps 采用模块化的 Flask Blueprint 架构，具有分层中间件：JWT 认证 → RBAC 守卫 → 模块路由 → AI 辅助层 → 数据持久化 → 计费层。每个模块都可独立部署。

ShieldOps sigue una arquitectura modular de Flask Blueprint con middleware en capas: autenticación JWT → guardia RBAC → enrutamiento de módulos → capa de asistencia IA → persistencia de datos → capa de facturación. Cada módulo es implementable de forma independiente.

┌─────────────────────────────────────────────────────────────────────────────┐
│                          🌐 USER REQUEST                                     │
│                    (Browser / CLI / CI/CD / API Client)                       │
└──────────────────────────┬──────────────────────────────────────────────────┘
                           │
                           ▼
┌────────────────────────────────────────────────────────────────────────────┐
│                      🔀 FLASK BLUEPRINT ROUTER                              │
│  route_blueprint.py  ·  auth_blueprint.py  ·  scan_blueprint.py            │
│  sbom_blueprint.py   ·  report_blueprint.py · webhook_blueprint.py         │
│  admin_blueprint.py  ·  billing_blueprint.py                               │
└──────────────────────────┬────────────────────────────────────────────────┘
                           │
                           ▼
┌────────────────────────────────────────────────────────────────────────────┐
│                    🔐 JWT AUTH MIDDLEWARE + RBAC GUARD                      │
│  • Token validation (RS256, expiry, issuer)                                │
│  • Role extraction: admin / analyst / viewer                                │
│  • Permission gate: route → required role → allow/deny                      │
│  • Rate limiter: 100 req/min (authenticated) / 20 req/min (unauthenticated) │
└────────────┬─────────────────────────────────┬──────────────────────────────┘
             │                                 │
             ▼                                 ▼
┌────────────────────────────┐  ┌────────────────────────────────────────────┐
│    🛡️ MODULE ROUTER         │  │       🔌 MIDDLEWARE CHAIN                  │
│                             │  │                                            │
│  • /scan/image              │  │  • Request logging (audit trail)           │
│  • /scan/dockerfile         │  │  • Pagination & sorting                    │
│  • /sbom/{id}               │  │  • CORS headers                            │
│  • /vulnerabilities         │  │  • Content negotiation (JSON/CSV/PDF)      │
│  • /reports/{id}            │  │  • Compression (gzip/brotli)               │
│  • /auth/login              │  │  • Cache control (ETag, If-None-Match)     │
│  • /admin/users             │  │                                            │
│  • /webhooks/github         │  └────────────────────────────────────────────┘
│  • /billing/*               │
└───────────┬─────────────────┘
            │
            ▼
┌────────────────────────────────────────────────────────────────────────────┐
│                      🤖 AI ASSISTANCE LAYER (OpenRouter / Gemini)           │
│                                                                             │
│  ┌────────────────────┐  ┌────────────────────┐  ┌──────────────────────┐  │
│  │  CVE Remediation   │  │  Dockerfile Fix     │  │  Natural Language   │  │
│  │  Engine            │  │  Generator          │  │  Query (NLQ)        │  │
│  └────────────────────┘  └────────────────────┘  └──────────────────────┘  │
│  ┌────────────────────┐  ┌────────────────────┐                           │ │
│  │  Compliance Report │  │  SBOM Enrichment   │                           │ │
│  │  Writer            │  │  (License, CPE)    │                           │ │
│  └────────────────────┘  └────────────────────┘                           │ │
└───────────┬──────────────────────────────────────────────┬──────────────────┘
            │                                              │
            ▼                                              ▼
┌────────────────────────────┐  ┌────────────────────────────────────────────┐
│   📊 DATA LAYER            │  │   💳 PAYMENT LAYER                         │
│                             │  │                                            │
│  ┌──────────────────────┐  │  │  ┌────────────────────┐  ┌──────────────┐  │
│  │  PostgreSQL 16       │  │  │  │  Kashier          │  │  PayPal      │  │
│  │  (primary, ACID)     │  │  │  │  • Subscriptions  │  │  • (Pending)  │  │
│  │  • blog_posts        │  │  │  │  • Invoices       │  │               │  │
│  │  • scan_results      │  │  │  │  • Webhooks       │  │               │  │
│  │  • vuln_cache        │  │  │  └────────────────────┘  └──────────────┘  │
│  │  • audit_logs        │  │  │                                            │
│  │  • users             │  │  └────────────────────────────────────────────┘
│  └──────────────────────┘  │
│  ┌──────────────────────┐  │
│  │  SQLite (dev/test)   │  │
│  └──────────────────────┘  │
└────────────────────────────┘

⚡3. Features & Modules#

⚡٣. الميزات والوحدات#

⚡3. 功能与模块#

⚡3. Funciones y Módulos#

🔌4. API Reference#

🔌٤. مرجع واجهة API#

🔌4. API 参考#

🔌4. Referencia de API#

All API endpoints below follow the prefix/api/v1/. Responses are JSON. Authentication via Authorization: Bearer header.

Note:The following routes are representative pattern descriptions. Exact endpoint paths and parameter schemas may vary — refer to the live API documentation or OpenAPI specification for authoritative definitions.

جميع نقاط API مسبوقة بـ/api/v1/. الردود بتنسيق JSON. المصادقة عبر ترويسة Authorization: Bearer .

ملاحظة:المسارات التالية هي أنماط تمثيلية. قد تختلف مسارات endpoints الدقيقة ومخططات المعاملات — راجع توثيق API المباشر أو مواصفات OpenAPI للتعريفات الرسمية.

以下所有 API 端点都以/api/v1/ 为前缀。响应格式为 JSON。通过 Authorization: Bearer 标头进行身份验证。

注意：以下路由是代表性模式描述。确切的端点路径和参数模式可能有所不同 — 请参阅实时 API 文档或 OpenAPI 规范以获取权威定义。

Todos los endpoints de API tienen el prefijo/api/v1/. Las respuestas son JSON. Autenticación mediante encabezado Authorization: Bearer .

Nota:Las siguientes rutas son descripciones de patrones representativos. Las rutas exactas de los endpoints y los esquemas de parámetros pueden variar — consulte la documentación de API en vivo o la especificación OpenAPI para definiciones autorizadas.

Authentication Header Format

تنسيق ترويسة المصادقة

认证标头格式

Formato de Encabezado de Autenticación

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwicm9sZSI6ImFkbWluIiwiaWF0IjoxNTE2MjM5MDIyLCJleHAiOjE1MTYyNDI2MjJ9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Rate Limits

حدود الطلبات

速率限制

Límites de tasa

Standard Error Responses

ردود الأخطاء القياسية

标准错误响应

Respuestas de Error Estándar

Endpoints#

نقاط النهاية#

端点#

Endpoints#

🔐5. Authentication & RBAC#

🔐٥. المصادقة والصلاحيات#

🔐5. 认证与 RBAC#

🔐5. Autenticación y RBAC#

JWT Flow

تدفق JWT

JWT 流程

Flujo JWT

  ┌──────────┐          ┌──────────────┐          ┌─────────────┐
  │  CLIENT   │          │  SHIELDOPS   │          │   DATABASE   │
  │ (Browser) │          │    API       │          │  (Postgres)  │
  └─────┬─────┘          └──────┬───────┘          └──────┬──────┘
        │                       │                         │
        │  POST /auth/login     │                         │
        │  {email, password}    │                         │
        ├──────────────────────►│                         │
        │                       │  SELECT hash, role      │
        │                       │  FROM users             │
        │                       ├─────────────────────────►│
        │                       │◄─────────────────────────┤
        │                       │                         │
        │                       │  bcrypt.verify(password) │
        │                       │  ↓ valid                 │
        │                       │  jwt.encode({            │
        │                       │    sub: user_id,         │
        │                       │    role: admin,          │
        │                       │    iat: now,             │
        │                       │    exp: now + 24h        │
        │                       │  })                      │
        │                       │                         │
        │  200 {access_token,   │                         │
        │       refresh_token,  │                         │
        │       expires_in: 86400}                        │
        │◄──────────────────────┤                         │
        │                       │                         │
        │  GET /api/v1/scan     │                         │
        │  Authorization:       │                         │
        │  Bearer          │                         │
        ├──────────────────────►│                         │
        │                       │  jwt.decode(token)      │
        │                       │  ↓ valid                │
        │                       │  ↓ role=admin → allowed  │
        │                       │  ↓ role=viewer → 403    │
        │                       │                         │
        │  200 {results: [...]}◄─┤                         │
        │◄──────────────────────┤                         │
        │                       │                         │
        │  POST /auth/refresh   │                         │
        │  {refresh_token}      │                         │
        ├──────────────────────►│                         │
        │  200 {access_token:   │                         │
        │        new_jwt,       │                         │
        │        expires_in: 86400}                       │
        │◄──────────────────────┤                         │

Token Expiry Defaults

القيم الافتراضية لانتهاء الرمز

令牌过期默认值

Valores predeterminados de caducidad del token

RBAC Permission Matrix

مصفوفة صلاحيات RBAC

RBAC 权限矩阵

Matriz de permisos RBAC

🔗6. Integrations#

🔗٦. التكاملات#

🔗6. 集成#

🔗6. Integraciones#

🚀7. Deployment#

🚀٧. النشر#

🚀7. 部署#

🚀7. Despliegue#

a) Local Development

أ) التطوير المحلي

a) 本地开发

a) Desarrollo local

# 1. Clone repository
git clone https://github.com/mohammedabdallahcv-creator/shieldops-launch-gate.git
cd shieldops

# 2. Create virtual environment
python3 -m venv .venv && source .venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure environment
cp .env.example .env
# Edit .env: DATABASE_URL, JWT_SECRET, OPENROUTER_API_KEY, etc.

# 5. Initialize database
flask db upgrade

# 6. Run development server
flask run --port 5000 --debug

Docker Compose (Quick Start)

Docker Compose (بداية سريعة)

Docker Compose（快速开始）

Docker Compose (inicio rápido)

# docker-compose.yml
version: "3.9"
services:
  shieldops:
    build: .
    ports:
      - "5000:5000"
    env_file: .env
    depends_on:
      - postgres
    volumes:
      - ./data:/app/data
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: shieldops
      POSTGRES_USER: shieldops
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data
volumes:
  pgdata:

b) Production (Docker / Render)

ب) الإنتاج (Docker / Render)

b) 生产环境 (Docker / Render)

b) Producción (Docker / Render)

# Docker build and run
docker build -t shieldops .
docker run -p 5000:5000 --env-file .env shieldops

# Or deploy via Render:
# 1. Push to GitHub
# 2. Connect repository to Render
# 3. Render auto-detects render.yaml:
#    - Web Service: gunicorn wsgi:app --workers 2 --timeout 180
#    - PostgreSQL: 16-alpine
#    - Cron Job: daily publisher
# 4. Set environment variables in Render Dashboard
# 5. Deploy

# Gunicorn (standalone):
gunicorn wsgi:app \
  --bind 0.0.0.0:5000 \
  --workers 2 \
  --threads 2 \
  --timeout 180 \
  --access-logfile - \
  --error-logfile -

c) Environment Variables

ج) متغيرات البيئة

c) 环境变量

c) Variables de entorno

d) Health Check

د) فحص الصحة

d) 健康检查

d) Verificación de estado

curl https://shieldops-ai.dev/health

{
  "status": "healthy",
  "version": "2.4.0",
  "db": "connected",
  "uptime": "14d 7h 32m",
  "scans_today": 147,
  "last_cve_sync": "2026-06-16T02:00:00Z"
}

📜8. Compliance & Security Standards#

📜٨. الامتثال والمعايير الأمنية#

📜8. 合规与安全标准#

📜8. Cumplimiento y Estándares de Seguridad#

PCI-DSS v4.0 Alignment Reference

مرجع التوافق مع PCI-DSS v4.0

PCI-DSS v4.0 对齐参考

Referencia de alineación PCI-DSS v4.0

The table below illustrates how ShieldOps AI module capabilities may support organizations working toward PCI-DSS v4.0 requirements. This is not a certification or guarantee of compliance.

CVE / CWE / CVSS Integration

تكامل CVE / CWE / CVSS

CVE / CWE / CVSS 集成

Integración CVE / CWE / CVSS

ShieldOps indexes CVE data from the National Vulnerability Database (NVD) and maps each vulnerability to its CWE weakness class. All findings are scored using CVSS v3.1 with temporal and environmental metrics.

تستورد ShieldOps بيانات CVE من قاعدة الثغرات الوطنية (NVD) وتربط كل ثغرة بنوع الضعف CWE الخاص بها. جميع النتائج تُسجل باستخدام CVSS v3.1 مع مقاييس زمنية وبيئية.

ShieldOps 从国家漏洞数据库 (NVD) 索引 CVE 数据，并将每个漏洞映射到其 CWE 弱点类别。所有发现均使用 CVSS v3.1 评分，包含时间和环境指标。

ShieldOps indexa datos CVE de la Base de Datos Nacional de Vulnerabilidades (NVD) y mapea cada vulnerabilidad a su clase de debilidad CWE. Todos los hallazgos se puntúan usando CVSS v3.1 con métricas temporales y ambientales.

{
  "cve_id": "CVE-2024-21626",
  "cvss_v31": {
    "base_score": 8.6,
    "severity": "HIGH",
    "vector": "CVSS:3.1/AV:L/AC:L/PR:N/UI:R/S:C/C:H/I:H/A:H",
    "attack_vector": "Local",
    "complexity": "Low"
  },
  "cwe_id": "CWE-22",
  "cwe_name": "Improper Limitation of a Pathname to a Restricted Directory",
  "affected_packages": ["runc>=1.1.0"],
  "fixed_in": ["runc 1.1.12"],
  "exploit_available": true
}

Data Handling & Retention Policy

سياسة معالجة البيانات والاحتفاظ

数据处理与保留政策

Política de manejo y retención de datos

Security Posture

الموقف الأمني

安全态势

Postura de seguridad

ShieldOps AI is designed with auditability, workflow traceability, and secure data handling as foundational requirements. The platform supports organizations in organizing findings, remediation workflows, and evidence collection for compliance-oriented programs.

تم تصميم ShieldOps AI مع قابلية التدقيق وتتبع سير العمل والمعالجة الآمنة للبيانات كمتطلبات أساسية. تدعم المنصة المؤسسات في تنظيم النتائج وسير عمل الإصلاح وجمع الأدلة لبرامج الامتثال.

ShieldOps AI 的设计以可审计性、工作流可追溯性和安全数据处理为基础要求。该平台支持组织整理发现、修复工作流和合规项目的证据收集。

ShieldOps AI está diseñado con auditabilidad, trazabilidad de flujos de trabajo y manejo seguro de datos como requisitos fundamentales. La plataforma ayuda a las organizaciones a organizar hallazgos, flujos de remediación y recopilación de evidencia para programas de cumplimiento.

Disclaimer

إخلاء مسؤولية

免责声明

Aviso legal

ShieldOps AI provides tooling to support compliance workflows and evidence organization. The platform does not confer certification, guarantee compliance with any specific framework, or eliminate security risk. Organizations remain responsible for independent validation, control implementation, and compliance determination by qualified assessors.

توفر ShieldOps AI أدوات لدعم سير عمل الامتثال وتنظيم الأدلة. لا تمنح المنصة شهادة امتثال لأي إطار محدد، ولا تضمن الامتثال، ولا تقضي على المخاطر الأمنية. تظل المؤسسات مسؤولة عن التحقق المستقل وتنفيذ الضوابط وتحديد الامتثال من قبل مقيمين مؤهلين.

ShieldOps AI 提供支持合规工作流和证据组织的工具。该平台不授予认证，不保证符合任何特定框架，也不消除安全风险。组织仍负责独立验证、控制实施和由合格评估员进行的合规性确定。

ShieldOps AI proporciona herramientas para apoyar flujos de trabajo de cumplimiento y organización de evidencia. La plataforma no otorga certificación, no garantiza el cumplimiento de ningún marco específico ni elimina el riesgo de seguridad. Las organizaciones siguen siendo responsables de la validación independiente, la implementación de controles y la determinación del cumplimiento por parte de evaluadores calificados.

📦9. Changelog / Roadmap#

📦٩. سجل التغييرات / الخريطة#

📦9. 更新日志 / 路线图#

📦9. Registro de cambios / Hoja de ruta#

Recent Updates

آخر التحديثات

最近更新

Actualizaciones recientes

Next Priorities

الأولويات القادمة

下一步优先事项

Próximas prioridades

🤝10. Contributing#

🤝١٠. المساهمة#

🤝10. 贡献#

🤝10. Contribuir#

Fork → Branch → PR Workflow

سير عمل: انسخ → أنشئ فرعاً → طلب سحب

Fork → 分支 → PR 工作流

Flujo de trabajo: Fork → Rama → PR

# 1. Fork the repository on GitHub
# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/shieldops.git
cd shieldops

# 3. Create a feature branch
git checkout -b feat/my-feature      # or fix/my-bugfix

# 4. Make changes and commit
git add .
git commit -m "feat: add runtime monitoring integration"

# 5. Push to your fork
git push origin feat/my-feature

# 6. Open a Pull Request on GitHub
#    - Target branch: main
#    - Title must follow Conventional Commits
#    - Include: What, Why, How, Testing

Code Style

نمط الكود

代码风格

Estilo de código

• Python:PEP 8 enforced viaflake8 + black (line length: 100)
• JavaScript:ESLint with Airbnb base config
• HTML/CSS:prettier + stylelint
• Commit messages:Conventional Commits (feat:, fix:, docs:, refactor:, test:)
• Branch naming:feat/ or fix/ prefix only — no dev-, feature/, or other prefixes

Pre-commit Checks

فحوصات ما قبل الالتزام

提交前检查

Verificaciones previas al commit

# Run all tests
pytest --cov=shieldops --cov-report=term-missing

# Lint Python
flake8 shieldops/ tests/

# Security scan
bandit -r shieldops/ -x tests/

# Type check (if type hints are used)
mypy shieldops/

Issue Templates

قوالب المشكلات

问题模板

Plantillas de issues

We provide three issue templates on GitHub:

نوفر ثلاثة قوالب مشكلات على GitHub:

我们在 GitHub 上提供三个问题模板：

Proporcionamos tres plantillas de issues en GitHub:

• 🐛 Bug Report— Describe the bug, steps to reproduce, expected vs actual behavior, logs/screenshots
• ✨ Feature Request— Use case, proposed solution, alternative approaches, priority
• 🔒 Security Disclosure—Do NOT open a public issue.Emailsecurity@shieldops-ai.dev instead. PGP key available on our website.
• 🐛 تقرير خطأ— وصف الخطأ، خطوات إعادة الإنتاج، السلوك المتوقع مقابل الفعلي، سجلات/لقطات شاشة
• ✨ طلب ميزة— حالة الاستخدام، الحل المقترح، البدائل، الأولوية
• 🔒 إفصاح أمني—لا تفتح مشكلة عامة.أرسل بريداً إلكترونياً إلىsecurity@shieldops-ai.dev. مفتاح PGP متاح على موقعنا.
• 🐛 错误报告— 描述错误、重现步骤、预期与实际行为、日志/截图
• ✨ 功能请求— 用例、建议的解决方案、替代方法、优先级
• 🔒 安全披露—不要公开提交问题。请发送电子邮件至security@shieldops-ai.dev。PGP 密钥可在我们的网站上获取。
• 🐛 Informe de error— Describa el error, pasos para reproducir, comportamiento esperado vs real, registros/capturas
• ✨ Solicitud de función— Caso de uso, solución propuesta, enfoques alternativos, prioridad
• 🔒 Divulgación de seguridad—No abra un issue público.Envíe un correo asecurity@shieldops-ai.dev. Clave PGP disponible en nuestro sitio web.

Security Disclosure Policy

سياسة الإفصاح الأمني

安全披露政策

Política de divulgación de seguridad

We take security seriously. If you discover a vulnerability, please follow our responsible disclosure process:

نحن نأخذ الأمان على محمل الجد. إذا اكتشفت ثغرة أمنية، يرجى اتباع عملية الإفصاح المسؤولة لدينا:

我们认真对待安全问题。如果您发现漏洞，请遵循我们的负责任的披露流程：

Tomamos la seguridad seriamente. Si descubre una vulnerabilidad, siga nuestro proceso de divulgación responsable:

1. Emailsecurity@shieldops-ai.dev with details (do NOT open a public issue)
2. Include: affected version, attack scenario, proof-of-concept (if available)
3. We acknowledge within 24 hours and provide an ETA for the fix
4. After the fix is released, we credit the reporter (unless anonymity is requested)
5. أرسل بريداً إلكترونياً إلىsecurity@shieldops-ai.dev مع التفاصيل (لا تفتح مشكلة عامة)
6. تضمين: الإصدار المتأثر، سيناريو الهجوم، إثبات المفهوم (إن وجد)
7. نؤكد الاستلام خلال 24 ساعة ونقدم وقتاً تقديرياً للإصلاح
8. بعد إصدار الإصلاح، ننسب الفضل للمُبلّغ (إلا إذا طلب عدم الكشف عن هويته)
9. 发送电子邮件至security@shieldops-ai.dev 提供详细信息（不要公开提交问题）
10. 包括：受影响的版本、攻击场景、概念验证（如有）
11. 我们在 24 小时内确认并提供修复的预计时间
12. 修复发布后，我们会感谢报告者（除非要求匿名）
13. Envíe un correo asecurity@shieldops-ai.dev con detalles (NO abra un issue público)
14. Incluya: versión afectada, escenario de ataque, prueba de concepto (si está disponible)
15. Reconocemos dentro de 24 horas y proporcionamos un ETA para la corrección
16. Después de lanzada la corrección, acreditamos al reportero (a menos que solicite anonimato)

SeeSECURITY.md in the repository root for the PGP key and full policy.

انظرSECURITY.md في جذر المستودع للحصول على مفتاح PGP والسياسة الكاملة.

请参阅仓库根目录中的SECURITY.md 了解 PGP 密钥和完整政策。

ConsulteSECURITY.md en la raíz del repositorio para la clave PGP y la política completa.