Laravel/PHP OpenAPI Migration Guide: cyber.trackr.live Implementation

This guide is specifically tailored for the cyber.trackr.live architecture and similar Laravel/PHP projects that use XML data sources instead of traditional databases.

Current Architecture Understanding

Based on the current setup:

• Laravel PHP framework on Apache
• XML XPath queries instead of SQL database queries
• Raw XML STIGs from DISA drops as data source
• Google Gemini AI for mitigation statement generation
• No traditional database - purposely designed this way

Migration Benefits for Your Architecture

Why OpenAPI-First Makes Sense for cyber.trackr.live

1. Keep Your Current Stack: Laravel + XML architecture stays unchanged
2. Automatic Client Generation: Ruby, Python, Go, TypeScript clients from one spec
3. Built-in Documentation: Interactive Swagger UI automatically generated
4. Community Contribution: Other developers can easily build on your API
5. Future-Proofing: When you scale, clients don't need to change

The "Where Do I Put My Code?" Answer for Laravel

cyber-trackr-laravel/
├── app/
│   ├── Http/
│   │   ├── Controllers/
│   │   │   └── Api/              # Your API controllers (minimal changes)
│   │   │       ├── DocumentsController.php
│   │   │       ├── CciController.php
│   │   │       └── RmfController.php
│   │   └── Middleware/
│   │       └── OpenApiValidation.php  # Optional: Add validation
│   └── Services/                     # Your existing business logic (SAFE)
│       ├── StigService.php           # Your XML XPath queries
│       ├── CciService.php
│       └── GeminiService.php         # Your AI integration
├── storage/
│   └── xml/                          # Your DISA XML files (unchanged)
├── routes/
│   └── api.php                       # Laravel routes (minimal updates)
├── public/
│   └── docs/                         # OpenAPI documentation
└── openapi.yaml                      # The OpenAPI specification

Migration Strategy for cyber.trackr.live

Phase 1: OpenAPI Specification (Already Done!)

✅ Complete - We've reverse-engineered your API into a comprehensive OpenAPI 3.1.1 specification that covers:

• All STIG/SRG endpoints
• CCI data endpoints
• RMF controls
• SCAP documents
• Proper error handling
• Real response examples

Phase 2: Minimal Laravel Integration

Step 1: Add OpenAPI Spec to Your Project

# Add to your existing Laravel project
cd /path/to/cyber-trackr-laravel
curl -o openapi.yaml https://raw.githubusercontent.com/mitre/cyber-trackr-live/main/openapi/openapi.yaml

Step 2: Update Your Existing Controllers (Minimal Changes)

Your existing controllers probably look something like this:

<?php
// app/Http/Controllers/Api/DocumentsController.php - YOUR EXISTING CODE
namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Services\StigService;
use Illuminate\Http\Request;

class DocumentsController extends Controller
{
    protected $stigService;

    public function __construct(StigService $stigService)
    {
        $this->stigService = $stigService;
    }

    public function index()
    {
        // Your existing XML XPath logic (unchanged)
        $documents = $this->stigService->getAllDocuments();
        
        return response()->json($documents);
    }

    public function show($title, $version, $release)
    {
        // Your existing XML XPath logic (unchanged)
        $document = $this->stigService->getDocument($title, $version, $release);
        
        if (!$document) {
            return response()->json(['error' => 'Document not found'], 404);
        }
        
        return response()->json($document);
    }
}

Step 3: Your Business Logic Stays Unchanged

<?php
// app/Services/StigService.php - YOUR EXISTING BUSINESS LOGIC (SAFE)
namespace App\Services;

use DOMDocument;
use DOMXPath;

class StigService
{
    protected $xmlPath;

    public function __construct()
    {
        $this->xmlPath = storage_path('xml/');
    }

    public function getAllDocuments()
    {
        // Your existing XML XPath queries (completely unchanged)
        $documents = [];
        
        // Your logic to scan XML files and extract document info
        $xmlFiles = glob($this->xmlPath . '*.xml');
        
        foreach ($xmlFiles as $file) {
            $dom = new DOMDocument();
            $dom->load($file);
            $xpath = new DOMXPath($dom);
            
            // Your existing XPath queries
            $title = $xpath->query('//title')->item(0)->nodeValue;
            $version = $xpath->query('//version')->item(0)->nodeValue;
            // ... rest of your existing logic
        }
        
        return $documents;
    }

    public function getDocument($title, $version, $release)
    {
        // Your existing XML XPath queries (completely unchanged)
        $xmlFile = $this->findXmlFile($title, $version, $release);
        
        if (!$xmlFile) {
            return null;
        }
        
        $dom = new DOMDocument();
        $dom->load($xmlFile);
        $xpath = new DOMXPath($dom);
        
        // Your existing XPath queries for document details
        $requirements = [];
        $vulnNodes = $xpath->query('//Rule');
        
        foreach ($vulnNodes as $node) {
            // Your existing requirement parsing logic
            $vulnId = $xpath->query('.//@id', $node)->item(0)->nodeValue;
            $title = $xpath->query('.//title', $node)->item(0)->nodeValue;
            // ... rest of your existing logic
            
            $requirements[$vulnId] = [
                'title' => $title,
                'rule' => $rule,
                'severity' => $severity,
                'mitigation' => $this->generateMitigation($vulnId) // Your AI call
            ];
        }
        
        return [
            'id' => $title,
            'title' => $title,
            'version' => $version,
            'release' => $release,
            'requirements' => $requirements
        ];
    }

    private function generateMitigation($vulnId)
    {
        // Your existing Google Gemini integration (unchanged)
        return app(GeminiService::class)->generateMitigation($vulnId);
    }
}

Step 4: Your AI Integration Stays the Same

<?php
// app/Services/GeminiService.php - YOUR EXISTING AI LOGIC (SAFE)
namespace App\Services;

use Illuminate\Support\Facades\Http;

class GeminiService
{
    protected $apiKey;

    public function __construct()
    {
        $this->apiKey = env('GEMINI_API_KEY');
    }

    public function generateMitigation($vulnId)
    {
        // Your existing Google Gemini API call (completely unchanged)
        $response = Http::withHeaders([
            'Authorization' => 'Bearer ' . $this->apiKey,
            'Content-Type' => 'application/json'
        ])->post('https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent', [
            'contents' => [
                'parts' => [
                    'text' => "Generate mitigation statement for vulnerability: {$vulnId}"
                ]
            ]
        ]);

        return $response->json()['candidates'][0]['content']['parts'][0]['text'];
    }
}

Phase 3: Add OpenAPI Documentation

Step 1: Serve OpenAPI Documentation

# Create public documentation directory
mkdir -p public/docs

# Add simple HTML page to serve Swagger UI

<!-- public/docs/index.html -->
<!DOCTYPE html>
<html>
<head>
    <title>Cyber Trackr API Documentation</title>
    <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@5.0.0/swagger-ui.css" />
</head>
<body>
    <div id="swagger-ui"></div>
    <script src="https://unpkg.com/swagger-ui-dist@5.0.0/swagger-ui-bundle.js"></script>
    <script>
        SwaggerUIBundle({
            url: '/openapi.yaml',
            dom_id: '#swagger-ui',
            presets: [
                SwaggerUIBundle.presets.apis,
                SwaggerUIBundle.presets.standalone
            ]
        });
    </script>
</body>
</html>

Step 2: Add Route to Serve OpenAPI Spec

// routes/web.php - Add this route
Route::get('/openapi.yaml', function () {
    return response()->file(base_path('openapi.yaml'))
        ->header('Content-Type', 'application/yaml');
});

Phase 4: Optional Enhancements

Add OpenAPI Request Validation (Optional)

<?php
// app/Http/Middleware/OpenApiValidation.php - Optional enhancement
namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class OpenApiValidation
{
    public function handle(Request $request, Closure $next)
    {
        // Optional: Add OpenAPI request validation
        // This would validate incoming requests against your OpenAPI spec
        
        return $next($request);
    }
}

Add CORS Headers (If Needed)

// app/Http/Middleware/Cors.php - If you need CORS
namespace App\Http\Middleware;

use Closure;

class Cors
{
    public function handle($request, Closure $next)
    {
        return $next($request)
            ->header('Access-Control-Allow-Origin', '*')
            ->header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS')
            ->header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
    }
}

Migration Timeline for cyber.trackr.live (Static Build Focus)

Week 1: Documentation Integration

• [ ] Add OpenAPI spec to Laravel project
• [ ] Set up Swagger UI at /docs
• [ ] Test documentation with existing API

Week 2: Static Build Development

• [ ] Create BuildStaticApi Laravel command
• [ ] Generate static JSON files from XML
• [ ] Test static files match current API responses
• [ ] Set up local static file serving

Week 3: AI Integration & Client Testing

• [ ] Move AI mitigation generation to build time
• [ ] Generate Ruby, Python, Go clients
• [ ] Test all clients against static API
• [ ] Performance testing and optimization

Week 4: Production Deployment

• [ ] Deploy static API to CDN (Netlify/CloudFlare)
• [ ] Set up automated DISA XML monitoring
• [ ] Configure CI/CD for automatic rebuilds
• [ ] Monitor performance and usage

Benefits Timeline

• Week 1: Professional documentation
• Week 2: Ultra-fast API responses (50ms vs 200ms+)
• Week 3: Multi-language client libraries
• Week 4: Infinite scalability + near-zero costs

Benefits for cyber.trackr.live

Immediate Benefits (Week 1)

1. Professional Documentation: Interactive Swagger UI
2. API Discoverability: Developers can easily understand your API
3. Client Libraries: Ruby, Python, Go, TypeScript clients automatically generated

Medium-term Benefits (Month 1)

1. Community Contributions: Other developers can build on your API
2. Reduced Support: Self-documenting API reduces questions
3. Future-Proofing: OpenAPI spec protects against breaking changes

Long-term Benefits (3-6 months)

1. Ecosystem Growth: Multiple client libraries in different languages
2. Enterprise Integration: Large organizations can easily integrate
3. API Governance: Clear contract for API evolution

AI Rate Limiting Strategy

Current Challenge

There are potential Google Gemini API limits with increased usage to consider.

Solutions

Option 1: Caching Strategy (Recommended)

// app/Services/GeminiService.php - Add caching
public function generateMitigation($vulnId)
{
    // Check cache first
    $cacheKey = "mitigation:{$vulnId}";
    $cached = cache()->remember($cacheKey, 3600, function () use ($vulnId) {
        return $this->callGeminiApi($vulnId);
    });
    
    return $cached;
}

Option 2: Rate Limiting

// app/Http/Middleware/RateLimitAI.php
public function handle($request, Closure $next)
{
    $key = 'ai_calls:' . $request->ip();
    $calls = cache()->get($key, 0);
    
    if ($calls >= 10) { // 10 calls per hour
        return response()->json(['error' => 'Rate limit exceeded'], 429);
    }
    
    cache()->put($key, $calls + 1, 3600);
    return $next($request);
}

Option 3: MITRE AI Integration (Future)

Once hosted with MITRE, potentially use MITRE's AI resources instead of Google Gemini.

Hosting Migration Strategy

Current Setup (cyber.trackr.live Environment)

• Laravel on Apache
• No database
• XML files in storage
• Google Gemini API calls

MITRE Hosting Options (Open Source Accounts)

Since cyber.trackr.live is purposely designed without a database and uses XML files, we have several hosting options under MITRE's open source accounts:

Option 1: Netlify (Recommended for Laravel)

• Static + Functions: Deploy Laravel as Netlify Functions
• File Storage: XML files in repo or external storage
• Custom Domain: cyber.trackr.live can point to Netlify
• CI/CD: Automatic deploys from GitHub
• Cost: Free under MITRE's open source account

Option 2: GitHub Pages + Actions

• GitHub Actions: Run Laravel in container for API
• Static Site: Documentation hosted on GitHub Pages
• Custom Domain: cyber.trackr.live CNAME to GitHub
• CI/CD: Built-in GitHub Actions
• Cost: Free for public repositories

Option 3: CloudFlare Pages + Workers

• CloudFlare Workers: Run PHP/Laravel logic
• Pages: Host static documentation
• Custom Domain: cyber.trackr.live through CloudFlare
• CDN: Built-in global CDN
• Cost: Free under MITRE's open source account

Recommended Approach: Netlify

Given this architecture, Netlify is the best fit:

# Project structure for Netlify
cyber-trackr-live/
├── netlify/
│   └── functions/          # Laravel converted to serverless functions
│       ├── api.php         # Main API handler
│       └── composer.json   # Dependencies
├── public/                 # Static documentation
│   ├── docs/              # Swagger UI
│   └── index.html         # Landing page
├── xml/                   # DISA XML files (in repo)
├── netlify.toml           # Netlify configuration
└── README.md

Migration Steps (Netlify)

1. Repository Setup: Move code to MITRE GitHub organization
2. Function Conversion: Convert Laravel routes to Netlify functions
3. XML Storage: Store XML files in repository or external storage
4. DNS Setup: Point cyber.trackr.live to Netlify
5. CI/CD: Automatic deploys on XML updates

Alternative: Keep Current Hosting + Add Documentation

If the current hosting setup is preferred:

# Hybrid approach
Current Server:
- cyber.trackr.live/api/*     # Existing Laravel API

MITRE Hosting (Netlify/GitHub Pages):
- docs.cyber.trackr.live      # OpenAPI documentation
- clients.cyber.trackr.live   # Client library downloads

This provides flexibility to migrate gradually or stay with current hosting while MITRE provides the ecosystem around it.

Success Metrics

Technical Metrics

• API response time < 200ms (maintain current performance)
• 99.9% uptime
• Client library adoption across languages
• Documentation usage analytics

Business Metrics

• Increased API usage without increased support load
• Community contributions to the ecosystem
• Enterprise adoption of client libraries
• Reduced time-to-integration for new users

Next Steps for Implementation

1. Review this approach - Does it fit your comfort level?
2. Test locally - Try adding OpenAPI spec to your current project
3. Leadership discussion - Present benefits and hosting options to your leadership
4. Choose hosting approach - Full migration vs. hybrid documentation approach
5. Gradual rollout - Start with documentation, then client generation

Future Architecture Options

Database Evolution Path (Optional)

If you want to move away from XML files in the future:

Option 1: SQLite (Minimal Change)

// Easy migration: XML → SQLite
// - Single file database (like XML files)
// - No server setup needed
// - Can run anywhere (Netlify, GitHub Actions, etc.)
// - Laravel built-in support

class StigService
{
    public function getAllDocuments()
    {
        // Instead of XML XPath...
        return DB::select('SELECT * FROM documents ORDER BY name, version');
    }
}

Option 2: PostgreSQL (Full Database)

// For high-traffic scenarios
// - Full relational database
// - Better performance at scale
// - ACID compliance
// - Complex queries and relationships

class StigService
{
    public function getAllDocuments()
    {
        return Document::with('requirements')
                      ->orderBy('name')
                      ->orderBy('version')
                      ->get();
    }
}

Static API Build (Recommended for cyber.trackr.live)

Given the read-heavy, stable data nature of cyber.trackr.live, static build is the optimal solution:

Build Process (Laravel Command)

// app/Console/Commands/BuildStaticApi.php
class BuildStaticApi extends Command
{
    protected $signature = 'build:static-api';
    
    public function handle()
    {
        $this->info('Building static API from XML files...');
        
        // Use your existing StigService logic
        $stigService = app(StigService::class);
        $geminiService = app(GeminiService::class);
        
        // Build all endpoints
        $this->buildStigs($stigService, $geminiService);
        $this->buildCcis();
        $this->buildRmfControls();
        
        $this->info('Static API build complete!');
    }
    
    private function buildStigs($stigService, $geminiService)
    {
        // Generate /api/stig.json
        $allStigs = $stigService->getAllDocuments();
        $this->saveJson('api/stig.json', $allStigs);
        
        // Generate individual STIG files
        foreach ($allStigs as $stigName => $versions) {
            foreach ($versions as $version) {
                $document = $stigService->getDocument(
                    $stigName, 
                    $version['version'], 
                    $version['release']
                );
                
                // Generate AI mitigations at build time
                foreach ($document['requirements'] as $vulnId => &$requirement) {
                    $requirement['mitigation'] = $geminiService->generateMitigation($vulnId);
                }
                
                $path = "api/stig/{$stigName}/{$version['version']}/{$version['release']}.json";
                $this->saveJson($path, $document);
            }
        }
    }
}

Generated File Structure

public/
├── api/
│   ├── stig.json                                    # All STIGs list
│   ├── stig/
│   │   ├── Juniper_SRX_Services_Gateway_ALG/
│   │   │   └── 3/
│   │   │       └── 3.json                          # Full document + AI mitigations
│   │   └── Windows_Server_2022/
│   │       └── 1/
│   │           └── 4.json
│   ├── cci.json                                     # All CCIs
│   ├── cci/
│   │   └── CCI-000001.json                         # Individual CCI details
│   └── rmf/
│       └── controls.json                           # RMF controls
└── docs/
    └── index.html                                   # OpenAPI documentation

Deployment Script

#!/bin/bash
# deploy-static-api.sh - Runs when DISA updates XML

# 1. Update XML files from DISA
wget -O storage/xml/latest.xml https://disa.mil/latest-stig.xml

# 2. Build static API (includes AI generation)
php artisan build:static-api

# 3. Deploy to CDN
rsync -av public/api/ cdn-bucket:/api/

# 4. Deploy documentation
rsync -av public/docs/ cdn-bucket:/docs/

echo "Static API deployed successfully!"

Benefits for cyber.trackr.live

• Performance: 20-50ms response times globally via CDN
• Scalability: Handles millions of requests without server load
• Cost: $0 server costs, minimal CDN costs
• AI Efficiency: Generate mitigations once, serve forever
• Reliability: No server failures, just CDN uptime (99.99%+)
• Simplicity: Just static files, no complex infrastructure

CI/CD Integration

# .github/workflows/build-api.yml
name: Build Static API
on:
  schedule:
    - cron: '0 6 * * *'  # Daily at 6 AM (check for DISA updates)
  push:
    paths: ['storage/xml/**']

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
      - name: Install dependencies
        run: composer install
      - name: Build static API
        run: php artisan build:static-api
      - name: Deploy to CDN
        run: |
          # Deploy to Netlify/CloudFlare/GitHub Pages
          npm install -g netlify-cli
          netlify deploy --prod --dir=public

Migration Path: Current Laravel → Static Build → Enhanced with Database (if needed)

🎯 Why Static Build is Perfect for cyber.trackr.live

Perfect Match for cyber.trackr.live's Characteristics:

1. Read-Heavy API: 99% GET requests, perfect for static files
2. Stable Data: DISA drops are periodic, not real-time updates
3. Structured Data: STIGs, CCIs, RMF controls have predictable schemas
4. No User State: No authentication, sessions, or personalization
5. Performance Critical: Developers want fast, reliable API responses

Game-Changing Benefits:

1. 🚀 Performance: 20-50ms response times globally (vs 200ms+ dynamic)
2. ♾️ Scalability: Handle millions of requests without server load
3. 💰 Cost: Near-zero ongoing costs (just CDN)
4. 🧠 AI Efficiency: Generate mitigations once at build time, serve forever
5. 🔧 Simplicity: Just static files, no complex infrastructure
6. 🛡️ Reliability: CDN uptime (99.99%+) vs server reliability

Migration Path:

1. Phase 1: Current Laravel API + OpenAPI docs
2. Phase 2: Static build implementation (this is the sweet spot!)
3. Phase 3: Enhanced with database only if needed (probably won't be)

For Leadership Discussion:

• Performance: 4x faster response times
• Scalability: Handle any traffic level
• Cost: Reduce from server costs to nearly free
• Reliability: Better uptime than current server
• Maintenance: Simpler deployment, fewer moving parts

The static build approach transforms cyber.trackr.live from a traditional API into a high-performance, infinitely scalable, low-cost solution while keeping all existing business logic intact!

Implementation Questions

1. Hosting preference - Full migration to MITRE hosting or hybrid approach?
2. Current deployment process - How do you currently deploy updates?
3. DISA XML updates - How often do you update XML files? Could this be automated?
4. AI usage patterns - What's your current Gemini API usage and scaling concerns?
5. Performance requirements - What response times do you need to maintain?
6. User authentication - Any plans for API authentication or rate limiting?
7. Future database interest - SQLite for simplicity or PostgreSQL for scale?
8. Static API consideration - Interest in pre-built JSON files for performance?

Hosting Decision Matrix

Factor	Keep Current + Docs	Netlify Migration	GitHub Pages	CloudFlare	Static API Build
Effort	Low	Medium	Medium	Medium	Medium
Risk	Minimal	Low	Low	Low	Low
Cost	Current costs	Free	Free	Free	Free
Scalability	Current limits	High	Medium	High	Infinite
Performance	Current	Good	Good	Excellent	Fastest
AI Integration	Current Gemini	Need alternative	Need alternative	Need alternative	Build-time only
Control	Full	Shared	Shared	Shared	Full
MITRE Brand	Documentation only	Full integration	Full integration	Full integration	Full integration
Database Future	XML → SQLite/PG	XML → SQLite/PG	Static files	Static files	Static → Database

Recommendation: Given cyber.trackr.live's read-heavy, stable data characteristics, Static API Build is the optimal long-term solution. Start with "Keep Current + Docs" to test, then migrate to static build for ultimate performance and infinite scalability.

This approach lets you keep your existing Laravel architecture while gaining all the benefits of OpenAPI-first development!