@hoanghainh/komagu 2.2.1 → 2.3.0

package/contracts/schemas/api-inventory-diff.schema.json

@@ -0,0 +1,213 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "lsa/api-inventory-diff.schema.json",
+  "title": "Komagu API Inventory Diff",
+  "type": "object",
+  "required": [
+    "version",
+    "generated_at",
+    "sources",
+    "summary",
+    "shadow_apis",
+    "zombie_apis",
+    "documented_missing_code",
+    "dormant_code"
+  ],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "enum": [
+        1
+      ]
+    },
+    "generated_at": {
+      "type": "string"
+    },
+    "sources": {
+      "type": "object",
+      "required": [
+        "routes_file",
+        "openapi_file"
+      ],
+      "properties": {
+        "routes_file": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "openapi_file": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "traffic_log_file": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": [
+        "total_code_routes",
+        "total_spec_endpoints",
+        "total_traffic_endpoints",
+        "shadow_count",
+        "zombie_count",
+        "missing_code_count",
+        "dormant_count"
+      ],
+      "properties": {
+        "total_code_routes": {
+          "type": "integer"
+        },
+        "total_spec_endpoints": {
+          "type": "integer"
+        },
+        "total_traffic_endpoints": {
+          "type": "integer"
+        },
+        "shadow_count": {
+          "type": "integer"
+        },
+        "zombie_count": {
+          "type": "integer"
+        },
+        "missing_code_count": {
+          "type": "integer"
+        },
+        "dormant_count": {
+          "type": "integer"
+        }
+      }
+    },
+    "shadow_apis": {
+      "type": "array",
+      "description": "Endpoints present in code or seen in traffic, but absent from OpenAPI specification.",
+      "items": {
+        "type": "object",
+        "required": [
+          "method",
+          "path",
+          "normalized",
+          "discovered_in"
+        ],
+        "properties": {
+          "method": {
+            "type": "string"
+          },
+          "path": {
+            "type": "string"
+          },
+          "normalized": {
+            "type": "string"
+          },
+          "discovered_in": {
+            "type": "string",
+            "enum": [
+              "code_only",
+              "traffic_only",
+              "code_and_traffic"
+            ]
+          },
+          "location": {
+            "type": "string"
+          },
+          "traffic_hits": {
+            "type": "integer"
+          }
+        }
+      }
+    },
+    "zombie_apis": {
+      "type": "array",
+      "description": "Endpoints marked as deprecated in OpenAPI spec, but still active/receiving live traffic.",
+      "items": {
+        "type": "object",
+        "required": [
+          "method",
+          "path",
+          "normalized",
+          "traffic_hits"
+        ],
+        "properties": {
+          "method": {
+            "type": "string"
+          },
+          "path": {
+            "type": "string"
+          },
+          "normalized": {
+            "type": "string"
+          },
+          "location": {
+            "type": "string"
+          },
+          "traffic_hits": {
+            "type": "integer"
+          },
+          "last_seen": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "documented_missing_code": {
+      "type": "array",
+      "description": "Endpoints declared in OpenAPI spec but not found implemented in code inventory.",
+      "items": {
+        "type": "object",
+        "required": [
+          "method",
+          "path",
+          "normalized"
+        ],
+        "properties": {
+          "method": {
+            "type": "string"
+          },
+          "path": {
+            "type": "string"
+          },
+          "normalized": {
+            "type": "string"
+          },
+          "summary": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "dormant_code": {
+      "type": "array",
+      "description": "Endpoints implemented in code and documented, but never seen in traffic log.",
+      "items": {
+        "type": "object",
+        "required": [
+          "method",
+          "path",
+          "normalized",
+          "location"
+        ],
+        "properties": {
+          "method": {
+            "type": "string"
+          },
+          "path": {
+            "type": "string"
+          },
+          "normalized": {
+            "type": "string"
+          },
+          "location": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/contracts/schemas/attack-chain.schema.json

@@ -0,0 +1,181 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "lsa/attack-chain.schema.json",
+  "title": "Komagu attack chain collection",
+  "type": "object",
+  "required": [
+    "version",
+    "chains",
+    "summary"
+  ],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "enum": [
+        1
+      ]
+    },
+    "generated_at": {
+      "type": "string"
+    },
+    "chains": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "chain_id",
+          "title",
+          "entry",
+          "steps",
+          "outcome",
+          "business_impact",
+          "severity",
+          "confidence",
+          "breaking_fixes"
+        ],
+        "properties": {
+          "chain_id": {
+            "type": "string",
+            "pattern": "^chain-[0-9]{3,}$"
+          },
+          "title": {
+            "type": "string"
+          },
+          "entry": {
+            "type": "string",
+            "enum": [
+              "anonymous",
+              "authenticated_user",
+              "tenant_admin"
+            ]
+          },
+          "steps": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "step_index",
+                "finding_id",
+                "role_in_chain",
+                "requires",
+                "gains"
+              ],
+              "properties": {
+                "step_index": {
+                  "type": "integer"
+                },
+                "finding_id": {
+                  "type": "string"
+                },
+                "category": {
+                  "type": "string"
+                },
+                "subtype": {
+                  "type": "string"
+                },
+                "location": {
+                  "type": "string"
+                },
+                "endpoint": {
+                  "type": "string"
+                },
+                "role_in_chain": {
+                  "type": "string",
+                  "enum": [
+                    "entry_point",
+                    "privilege_gain",
+                    "access",
+                    "impact"
+                  ]
+                },
+                "requires": {
+                  "type": "string"
+                },
+                "gains": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "explanation": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "outcome": {
+            "type": "string"
+          },
+          "business_impact": {
+            "type": "string"
+          },
+          "severity": {
+            "type": "string",
+            "enum": [
+              "critical",
+              "high",
+              "medium",
+              "low"
+            ]
+          },
+          "confidence": {
+            "type": "string",
+            "enum": [
+              "confirmed",
+              "likely",
+              "needs_review"
+            ]
+          },
+          "breaking_fixes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "narrative": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": [
+        "total_chains",
+        "top_breaking_fixes"
+      ],
+      "properties": {
+        "total_chains": {
+          "type": "integer"
+        },
+        "by_severity": {
+          "type": "object"
+        },
+        "top_breaking_fixes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "finding_id",
+              "chains_broken"
+            ],
+            "properties": {
+              "finding_id": {
+                "type": "string"
+              },
+              "category": {
+                "type": "string"
+              },
+              "location": {
+                "type": "string"
+              },
+              "chains_broken": {
+                "type": "integer"
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/contracts/schemas/bas-scenario.schema.json

@@ -0,0 +1,217 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "contracts/schemas/bas-scenario.schema.json",
+  "title": "Breach & Attack Simulation (BAS) Declarative Scenario",
+  "description": "Schema for declarative incident simulation files in Komagu BAS.",
+  "type": "object",
+  "required": [
+    "id",
+    "version",
+    "title",
+    "status",
+    "incident",
+    "mappings",
+    "parameters",
+    "steps",
+    "scoring"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+      "description": "Unique slug identifier for the scenario."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+(\\.[0-9]+)?$",
+      "description": "Semantic version of the scenario definition."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 5,
+      "description": "Human-readable scenario title."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["draft", "approved", "retired"],
+      "description": "Governance review lifecycle status. Only approved scenarios run without explicit override."
+    },
+    "approved_by": {
+      "type": "string",
+      "description": "Sign-off auditor or security team member identity."
+    },
+    "approved_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of audit approval."
+    },
+    "incident": {
+      "type": "object",
+      "required": ["name", "date", "summary", "references"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Historical breach or landmark incident name."
+        },
+        "date": {
+          "type": "string",
+          "description": "Date or year of the incident."
+        },
+        "summary": {
+          "type": "string",
+          "description": "Executive description of the real-world attack."
+        },
+        "references": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1,
+          "description": "Public advisories, news reports, or CVE references."
+        }
+      }
+    },
+    "mappings": {
+      "type": "object",
+      "properties": {
+        "cwe": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "CWE numbers related to the attack (e.g. ['CWE-639', 'CWE-284'])."
+        },
+        "owasp_api": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "OWASP API Security Top 10 IDs (e.g. ['API1:2023'])."
+        },
+        "mitre_attack": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "MITRE ATT&CK technique IDs (e.g. ['T1059', 'T1552'])."
+        }
+      }
+    },
+    "parameters": {
+      "type": "object",
+      "description": "Configurable parameters with defaults.",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["default", "description"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["string", "integer", "boolean", "list"],
+            "default": "string"
+          },
+          "default": {},
+          "description": { "type": "string" }
+        }
+      }
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["name", "type"],
+        "properties": {
+          "name": { "type": "string" },
+          "description": { "type": "string" },
+          "type": {
+            "type": "string",
+            "enum": ["http_request", "storage_worm_check", "custom_probe"]
+          },
+          "destructive": {
+            "type": "boolean",
+            "default": false,
+            "description": "If true, changes or deletes state; requires --allow-destructive."
+          },
+          "repeat": {
+            "type": "object",
+            "description": "Loop configuration over an array parameter.",
+            "required": ["param_name", "as_var"],
+            "properties": {
+              "param_name": { "type": "string" },
+              "as_var": { "type": "string" }
+            }
+          },
+          "request": {
+            "type": "object",
+            "properties": {
+              "method": {
+                "type": "string",
+                "enum": ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"],
+                "default": "GET"
+              },
+              "path": { "type": "string" },
+              "query": { "type": "object", "additionalProperties": { "type": "string" } },
+              "headers": { "type": "object", "additionalProperties": { "type": "string" } },
+              "body": { "type": "string" }
+            }
+          },
+          "expect_secure": {
+            "type": "object",
+            "description": "Conditions indicating the system successfully mitigated or blocked the attack.",
+            "properties": {
+              "status_codes": {
+                "type": "array",
+                "items": { "type": "integer" }
+              },
+              "body_not_contains": {
+                "type": "array",
+                "items": { "type": "string" }
+              }
+            }
+          },
+          "expect_vulnerable": {
+            "type": "object",
+            "description": "Conditions indicating the system leaked data or was compromised.",
+            "properties": {
+              "status_codes": {
+                "type": "array",
+                "items": { "type": "integer" }
+              },
+              "body_contains": {
+                "type": "array",
+                "items": { "type": "string" }
+              },
+              "body_matches_regex": {
+                "type": "string"
+              }
+            }
+          },
+          "storage_check": {
+            "type": "object",
+            "description": "WORM storage compliance probe parameters.",
+            "properties": {
+              "operations": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "enum": ["overwrite", "truncate", "delete"]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "scoring": {
+      "type": "object",
+      "required": ["strategy", "recommendations"],
+      "properties": {
+        "strategy": {
+          "type": "string",
+          "enum": ["ratio", "all_or_nothing"],
+          "default": "ratio"
+        },
+        "recommendations": {
+          "type": "object",
+          "required": ["remediation", "passed"],
+          "properties": {
+            "remediation": { "type": "string" },
+            "passed": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}