Deploymentcenter BotandClaude Opus 5
e7fbc85db4
Sicherheit
- install_db.php war ohne Authentifizierung erreichbar und setzte bei jedem
Aufruf das Admin-Passwort auf einen fest im Code stehenden Wert zurück.
Jetzt Auth-Pflicht; ein Konto wird nur bei leerer Benutzertabelle angelegt.
- Stored XSS im Bugtracker-Detail-Modal: Titel, Beschreibung, Fehlermeldung,
Stacktrace und Kommentare gingen ungefiltert durch innerHTML.
- report.php, projects.php und das Veröffentlichen von Releases verlangen jetzt
zwingend ein Token. Publish war zuvor völlig ungeschützt.
- CSRF-Token in allen Formularen, Session-Regenerierung nach Login,
Drosselung fehlgeschlagener Anmeldeversuche.
- Zugangsdaten aus der Versionskontrolle entfernt (Serverdaten.txt,
config.php, .htpasswd, deploy_config.json). Historie enthält sie weiterhin,
Rotation erforderlich (siehe docs/UPGRADE.md).
- Token-Validierung nur noch über SHA-256-Hash; expires_at wird ausgewertet.
Behobene 500er
- Audit::log() war in index.php weder eingebunden noch importiert. Jeder
Klick auf "Aktivierung freigeben" endete in einem Fatal Error.
- Derselbe benannte PDO-Platzhalter mehrfach je Statement (:id in
revokeToken/deleteToken, :q siebenfach in der Volltextsuche). Bei
EMULATE_PREPARES=false ist das nicht zulässig und warf HY093.
- Migration 005 nutzte dynamisches SQL, dessen Semikolons in String-Literalen
vom alten explode(';')-Installer als Statement-Ende gelesen wurden. Sie
schlug still fehl, wodurch push_id/target_agent/tags dauerhaft fehlten.
- Monitor-Umbenennung ohne Transaktion, verschachtelte Transaktionen im
RateLimiter.
Funktionale Korrekturen
- Der Watchdog-Evaluator fehlte vollständig: Monitor-Zustände änderten sich nur
beim Eintreffen eines Heartbeats, ein ausgefallenes System blieb dauerhaft
"up". Erster Lauf auf dem Produktivsystem: 7 von 10 Monitoren waren
tatsächlich seit über einem Tag nicht erreichbar.
- Das Feld "os" fehlte im Monitor-Dialog, wurde aber gespeichert und löschte
damit bei jedem Speichern das Betriebssystem.
- Der Resolve-Dialog existierte im HTML nicht; der Button war funktionslos.
- Versionsvergleich erfolgte lexikografisch, wodurch 1.9.0 als neuer galt
als 1.10.0.
- Schreiboperationen meldeten Erfolg auch für nicht existierende IDs.
- Post/Redirect/Get gegen doppelte Einträge beim Neuladen.
Neue Struktur
- src/bootstrap.php mit PSR-4-Autoloader ersetzt die require-Ketten.
- Core: Config, Http, Csrf, ApiAuth, Logger, Migrator, ErrorReporter.
- Migrator mit zeichenweisem SQL-Parser, dc_migrations und Baseline-Verfahren,
damit bestehende Installationen keine Beispieldaten zurückbekommen.
Agenten-Workflow
- Claim/Lease: Items werden exklusiv übernommen, damit nicht zwei Agenten am
selben Problem arbeiten. action=next holt und reserviert in einem Zug.
- Idempotenz über client_ref, Deduplizierung auch für Feature Requests,
Erkennung von Regressionen, automatische Eskalation des Schweregrads.
- Strukturierter Code-Kontext (repo_url, commit_sha, file_path, line_no).
- Delta-Abfragen über updated_since, Pagination, Bulk-Update.
- Beim Veröffentlichen eines Releases schließen sich Items mit passendem
resolved_in_build selbst.
- Ausgehende Webhooks mit HMAC-Signatur, /api/health, /api/openapi.json.
- Unbehandelte Fehler meldet die Plattform in ihren eigenen Bugtracker.
WebUI
- Serverseitige Filterung mit Pagination statt Rendern aller Datensätze.
- Migrations-Schranke, Evaluator-Warnung, Übersicht aktiver Agenten.
Zeitstempel liegen in der Datenbank durchgängig in UTC und werden für die
Anzeige in die App-Zeitzone umgerechnet.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
309 lines
16 KiB
PHP
309 lines
16 KiB
PHP
<?php
|
|
|
|
/**
|
|
* GET /api/openapi.json
|
|
*
|
|
* Maschinenlesbare Beschreibung der Schnittstelle. Ersetzt den frueher fest
|
|
* im WebUI hinterlegten Textblock: ein Agent kann sich hier selbst orientieren,
|
|
* ohne dass eine Prompt-Vorlage gepflegt werden muss.
|
|
*/
|
|
|
|
declare(strict_types=1);
|
|
|
|
require_once __DIR__ . '/../../src/bootstrap.php';
|
|
|
|
use Deploymentcenter\Core\Config;
|
|
use Deploymentcenter\Core\Http;
|
|
use Deploymentcenter\Modules\Bugtracker\BugRepo;
|
|
use Deploymentcenter\Core\TokenManager;
|
|
|
|
Http::beginJson(['GET', 'OPTIONS'], true);
|
|
|
|
$baseUrl = Http::baseUrl();
|
|
|
|
$errorResponse = [
|
|
'description' => 'Fehler',
|
|
'content' => ['application/json' => ['schema' => ['$ref' => '#/components/schemas/Error']]],
|
|
];
|
|
|
|
$spec = [
|
|
'openapi' => '3.0.3',
|
|
'info' => [
|
|
'title' => 'Deploymentcenter API',
|
|
'version' => (string)Config::get('app.version', '2.0.0'),
|
|
'description' =>
|
|
"Zentrale Schnittstelle fuer Bugtracker, UpdateService, Watchdog und Token-Provisionierung.\n\n"
|
|
. "Authentifizierung ueber `Authorization: Bearer <token>` oder `X-Agent-Token`.\n"
|
|
. "Tokens werden im WebUI erzeugt (Master-Token) und koennen sich per\n"
|
|
. "`/api/tokens/v1/provision` selbst in Sub-Tokens aufteilen.\n\n"
|
|
. "Typischer Agenten-Ablauf:\n"
|
|
. "1. `POST /api/bugtracker/v1/manage?action=next` - naechstes Item holen und uebernehmen\n"
|
|
. "2. Arbeiten, Zwischenstand per `?action=comment` dokumentieren\n"
|
|
. "3. `?action=resolve` mit `resolved_in_build`\n"
|
|
. "4. Beim Release meldet `POST /api/updateservice/v1/publish` den Build; passende Items schliessen sich selbst.",
|
|
],
|
|
'servers' => [['url' => $baseUrl]],
|
|
'components' => [
|
|
'securitySchemes' => [
|
|
'bearerAuth' => ['type' => 'http', 'scheme' => 'bearer'],
|
|
'agentToken' => ['type' => 'apiKey', 'in' => 'header', 'name' => 'X-Agent-Token'],
|
|
],
|
|
'schemas' => [
|
|
'Error' => [
|
|
'type' => 'object',
|
|
'properties' => [
|
|
'status' => ['type' => 'string', 'enum' => ['error']],
|
|
'error' => [
|
|
'type' => 'object',
|
|
'properties' => [
|
|
'code' => ['type' => 'string', 'description' => 'Stabiler, maschinenlesbarer Fehlercode'],
|
|
'message' => ['type' => 'string'],
|
|
],
|
|
],
|
|
],
|
|
],
|
|
'BugtrackerItem' => [
|
|
'type' => 'object',
|
|
'properties' => [
|
|
'id' => ['type' => 'integer'],
|
|
'project_slug' => ['type' => 'string'],
|
|
'type' => ['type' => 'string', 'enum' => BugRepo::TYPES],
|
|
'title' => ['type' => 'string'],
|
|
'description' => ['type' => 'string', 'nullable' => true],
|
|
'error_message' => ['type' => 'string', 'nullable' => true],
|
|
'stack_trace' => ['type' => 'string', 'nullable' => true],
|
|
'environment' => ['type' => 'string', 'enum' => BugRepo::ENVIRONMENTS],
|
|
'severity' => ['type' => 'string', 'enum' => BugRepo::SEVERITIES],
|
|
'status' => ['type' => 'string', 'enum' => BugRepo::STATUSES],
|
|
'occurrence_count' => ['type' => 'integer'],
|
|
'claimed_by' => ['type' => 'string', 'nullable' => true],
|
|
'lease_until' => ['type' => 'string', 'format' => 'date-time', 'nullable' => true],
|
|
'repo_url' => ['type' => 'string', 'nullable' => true],
|
|
'git_branch' => ['type' => 'string', 'nullable' => true],
|
|
'commit_sha' => ['type' => 'string', 'nullable' => true],
|
|
'file_path' => ['type' => 'string', 'nullable' => true],
|
|
'line_no' => ['type' => 'integer', 'nullable' => true],
|
|
'resolved_in_build' => ['type' => 'string', 'nullable' => true],
|
|
'updated_at' => ['type' => 'string', 'format' => 'date-time'],
|
|
],
|
|
],
|
|
'ReportRequest' => [
|
|
'type' => 'object',
|
|
'required' => ['title'],
|
|
'properties' => [
|
|
'project_slug' => ['type' => 'string', 'example' => 'deploymentcenter'],
|
|
'type' => ['type' => 'string', 'enum' => BugRepo::TYPES, 'default' => 'bug'],
|
|
'title' => ['type' => 'string', 'maxLength' => 255],
|
|
'description' => ['type' => 'string'],
|
|
'error_message' => ['type' => 'string'],
|
|
'stack_trace' => ['type' => 'string'],
|
|
'severity' => ['type' => 'string', 'enum' => BugRepo::SEVERITIES],
|
|
'environment' => ['type' => 'string', 'enum' => BugRepo::ENVIRONMENTS],
|
|
'build_version' => ['type' => 'string'],
|
|
'push_id' => ['type' => 'string'],
|
|
'target_agent' => ['type' => 'string'],
|
|
'tags' => ['type' => 'string', 'description' => 'Kommagetrennt'],
|
|
'client_ref' => [
|
|
'type' => 'string',
|
|
'description' => 'Idempotenz-Schluessel. Ein erneuter Aufruf mit demselben Wert legt kein Duplikat an. Alternativ als Header Idempotency-Key.',
|
|
],
|
|
'repo_url' => ['type' => 'string'],
|
|
'git_branch' => ['type' => 'string'],
|
|
'commit_sha' => ['type' => 'string'],
|
|
'file_path' => ['type' => 'string'],
|
|
'line_no' => ['type' => 'integer'],
|
|
'context' => ['type' => 'object', 'description' => 'Beliebiger strukturierter Zusatzkontext'],
|
|
],
|
|
],
|
|
],
|
|
],
|
|
'security' => [['bearerAuth' => []], ['agentToken' => []]],
|
|
'paths' => [
|
|
|
|
'/api/health' => [
|
|
'get' => [
|
|
'tags' => ['System'],
|
|
'summary' => 'Verfuegbarkeit und Schema-Status',
|
|
'security' => [],
|
|
'responses' => ['200' => ['description' => 'Zustand'], '503' => ['description' => 'Nicht bereit']],
|
|
],
|
|
],
|
|
|
|
'/api/bugtracker/v1/report' => [
|
|
'post' => [
|
|
'tags' => ['Bugtracker'],
|
|
'summary' => 'Bug, Feature Request oder Idee melden',
|
|
'description' => 'Benoetigt den Scope bugtracker:report. Gleiche Fehler werden automatisch zusammengefasst und hochgezaehlt.',
|
|
'requestBody' => [
|
|
'required' => true,
|
|
'content' => ['application/json' => ['schema' => ['$ref' => '#/components/schemas/ReportRequest']]],
|
|
],
|
|
'responses' => [
|
|
'201' => ['description' => 'Neu angelegt'],
|
|
'200' => ['description' => 'Bestehendes Item aktualisiert (Duplikat oder Idempotenz-Treffer)'],
|
|
'401' => $errorResponse,
|
|
'429' => $errorResponse,
|
|
],
|
|
],
|
|
],
|
|
|
|
'/api/bugtracker/v1/projects' => [
|
|
'get' => [
|
|
'tags' => ['Bugtracker'],
|
|
'summary' => 'Projekte auflisten (Discovery)',
|
|
'description' => 'Benoetigt den Scope bugtracker:read.',
|
|
'responses' => ['200' => ['description' => 'Projektliste'], '401' => $errorResponse],
|
|
],
|
|
],
|
|
|
|
'/api/bugtracker/v1/manage' => [
|
|
'get' => [
|
|
'tags' => ['Bugtracker'],
|
|
'summary' => 'Items lesen',
|
|
'description' => 'Scope bugtracker:read. action=list|get|stats|projects.',
|
|
'parameters' => [
|
|
['name' => 'action', 'in' => 'query', 'schema' => ['type' => 'string', 'enum' => ['list', 'get', 'stats', 'projects'], 'default' => 'list']],
|
|
['name' => 'id', 'in' => 'query', 'schema' => ['type' => 'integer'], 'description' => 'Pflicht bei action=get'],
|
|
['name' => 'project_slug', 'in' => 'query', 'schema' => ['type' => 'string']],
|
|
['name' => 'status', 'in' => 'query', 'schema' => ['type' => 'string'], 'description' => 'Mehrere kommagetrennt, z. B. open,in_progress'],
|
|
['name' => 'severity', 'in' => 'query', 'schema' => ['type' => 'string'], 'description' => 'Mehrere kommagetrennt'],
|
|
['name' => 'target_agent', 'in' => 'query', 'schema' => ['type' => 'string']],
|
|
['name' => 'unclaimed_only', 'in' => 'query', 'schema' => ['type' => 'boolean']],
|
|
['name' => 'updated_since', 'in' => 'query', 'schema' => ['type' => 'string', 'format' => 'date-time'], 'description' => 'Delta-Abfrage fuer Polling'],
|
|
['name' => 'order', 'in' => 'query', 'schema' => ['type' => 'string', 'enum' => ['newest', 'oldest', 'updated', 'severity', 'occurrences']]],
|
|
['name' => 'limit', 'in' => 'query', 'schema' => ['type' => 'integer', 'default' => 100, 'maximum' => 500]],
|
|
['name' => 'offset', 'in' => 'query', 'schema' => ['type' => 'integer', 'default' => 0]],
|
|
],
|
|
'responses' => ['200' => ['description' => 'Trefferliste mit total/has_more'], '401' => $errorResponse],
|
|
],
|
|
'post' => [
|
|
'tags' => ['Bugtracker'],
|
|
'summary' => 'Items veraendern',
|
|
'description' =>
|
|
"Scope bugtracker:manage.\n\n"
|
|
. "- `action=next` holt die naechsten offenen Items und uebernimmt sie exklusiv\n"
|
|
. "- `action=claim&id=` uebernimmt ein bestimmtes Item (409 wenn bereits vergeben)\n"
|
|
. "- `action=release&id=` gibt es wieder frei\n"
|
|
. "- `action=comment&id=` haengt einen Ermittlungsschritt an\n"
|
|
. "- `action=status&id=` setzt den Status\n"
|
|
. "- `action=update&id=` aendert mehrere Felder\n"
|
|
. "- `action=resolve&id=` schliesst mit resolved_in_build\n"
|
|
. "- `action=bulk_update` aendert mehrere Items (ids[] + updates{})",
|
|
'parameters' => [
|
|
['name' => 'action', 'in' => 'query', 'required' => true, 'schema' => ['type' => 'string', 'enum' => ['claim', 'next', 'release', 'comment', 'status', 'update', 'resolve', 'bulk_update']]],
|
|
['name' => 'id', 'in' => 'query', 'schema' => ['type' => 'integer']],
|
|
],
|
|
'responses' => [
|
|
'200' => ['description' => 'Erfolg'],
|
|
'409' => ['description' => 'Item bereits von einem anderen Agenten uebernommen'],
|
|
'401' => $errorResponse,
|
|
],
|
|
],
|
|
],
|
|
|
|
'/api/updateservice/v1/check' => [
|
|
'get' => [
|
|
'tags' => ['UpdateService'],
|
|
'summary' => 'Auf Update pruefen',
|
|
'security' => [],
|
|
'parameters' => [
|
|
['name' => 'product', 'in' => 'query', 'required' => true, 'schema' => ['type' => 'string']],
|
|
['name' => 'version', 'in' => 'query', 'required' => true, 'schema' => ['type' => 'string']],
|
|
['name' => 'channel', 'in' => 'query', 'schema' => ['type' => 'string', 'default' => 'prod']],
|
|
],
|
|
'responses' => ['200' => ['description' => 'Vergleich nach semantischer Versionsordnung']],
|
|
],
|
|
],
|
|
|
|
'/api/updateservice/v1/publish' => [
|
|
'post' => [
|
|
'tags' => ['UpdateService'],
|
|
'summary' => 'Release veroeffentlichen',
|
|
'description' => 'Scope updateservice:publish. Schliesst automatisch alle Bugtracker-Items, deren resolved_in_build dieser Version entspricht.',
|
|
'requestBody' => [
|
|
'required' => true,
|
|
'content' => ['application/json' => ['schema' => [
|
|
'type' => 'object',
|
|
'required' => ['product_slug', 'version', 'download_url'],
|
|
'properties' => [
|
|
'product_slug' => ['type' => 'string'],
|
|
'version' => ['type' => 'string', 'example' => '1.4.3'],
|
|
'channel' => ['type' => 'string', 'default' => 'prod'],
|
|
'download_url' => ['type' => 'string'],
|
|
'sha256_hash' => ['type' => 'string', 'pattern' => '^[0-9a-fA-F]{64}$'],
|
|
'git_commit' => ['type' => 'string'],
|
|
'size_bytes' => ['type' => 'integer'],
|
|
'release_notes' => ['type' => 'string'],
|
|
'is_critical' => ['type' => 'boolean'],
|
|
],
|
|
]]],
|
|
],
|
|
'responses' => ['201' => ['description' => 'Angelegt'], '200' => ['description' => 'Aktualisiert'], '401' => $errorResponse],
|
|
],
|
|
],
|
|
|
|
'/api/watchdog/v1/ping' => [
|
|
'post' => [
|
|
'tags' => ['Watchdog'],
|
|
'summary' => 'Heartbeat senden',
|
|
'description' => 'Scope watchdog:ping. Alternativ ein Agent-Token aus watchdog_agent_tokens.',
|
|
'requestBody' => [
|
|
'required' => true,
|
|
'content' => ['application/json' => ['schema' => [
|
|
'type' => 'object',
|
|
'required' => ['source'],
|
|
'properties' => [
|
|
'source' => ['type' => 'string'],
|
|
'instance' => ['type' => 'string', 'default' => 'default'],
|
|
'status' => ['type' => 'string', 'enum' => ['ok', 'warning', 'error']],
|
|
'interval' => ['type' => 'integer', 'description' => 'Erwarteter Abstand in Sekunden; danach gilt der Monitor als auffaellig'],
|
|
'message' => ['type' => 'string'],
|
|
'metrics' => ['type' => 'object'],
|
|
'os' => ['type' => 'string'],
|
|
],
|
|
]]],
|
|
],
|
|
'responses' => ['200' => ['description' => 'Empfangen'], '401' => $errorResponse],
|
|
],
|
|
],
|
|
|
|
'/api/watchdog/v1/evaluate' => [
|
|
'get' => [
|
|
'tags' => ['Watchdog'],
|
|
'summary' => 'Evaluationslauf ausloesen',
|
|
'description' => 'Nur mit Shared Key oder angemeldeter Sitzung. Per Cron minuetlich aufrufen, sonst bleiben ausgefallene Monitore gruen.',
|
|
'responses' => ['200' => ['description' => 'Ergebnis des Laufs'], '401' => $errorResponse],
|
|
],
|
|
],
|
|
|
|
'/api/tokens/v1/provision' => [
|
|
'post' => [
|
|
'tags' => ['Tokens'],
|
|
'summary' => 'Sub-Token aus Master-Token erzeugen',
|
|
'description' => 'Master-Token im Header X-Master-Token. Rechte koennen nur eingeschraenkt, nicht erweitert werden.',
|
|
'requestBody' => [
|
|
'content' => ['application/json' => ['schema' => [
|
|
'type' => 'object',
|
|
'properties' => [
|
|
'client_name' => ['type' => 'string'],
|
|
'instance_id' => ['type' => 'string'],
|
|
'scopes' => ['type' => 'array', 'items' => ['type' => 'string', 'enum' => TokenManager::KNOWN_SCOPES]],
|
|
'environment' => ['type' => 'string', 'enum' => TokenManager::ENVIRONMENTS],
|
|
],
|
|
]]],
|
|
],
|
|
'responses' => ['201' => ['description' => 'Sub-Token erstellt'], '403' => $errorResponse],
|
|
],
|
|
],
|
|
],
|
|
];
|
|
|
|
// Direkte Ausgabe statt Http::ok(), damit die Spezifikation nicht in einen
|
|
// status-Umschlag verpackt wird.
|
|
if (!headers_sent()) {
|
|
header('Content-Type: application/json; charset=utf-8');
|
|
header('Cache-Control: public, max-age=300');
|
|
}
|
|
|
|
echo json_encode($spec, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
|