documents

.github/skills/dependency-inventory/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: Dependency Inventory
+description: Detect and export Maven and Gradle dependencies into normalized JSON
+---
+
+# Dependency Inventory Skill
+
+This skill detects Maven and Gradle projects and exports
+their resolved dependencies into a normalized JSON format.
+
+## Supported Build Tools
+
+- Maven
+- Gradle
+
+## Workflow
+
+1. Detect build tool
+2. Execute dependency export
+3. Normalize dependency output
+4. Generate dependency-inventory.json
+
+## Maven
+
+Preferred command:
+
+```bash
+./mvnw dependency:tree \
+  -DoutputType=json \
+  -DoutputFile=dependency-tree.json
+````
+
+Fallback:
+
+```bash
+mvn dependency:tree \
+  -DoutputType=json \
+  -DoutputFile=dependency-tree.json
+```
+
+## Gradle
+
+Preferred command:
+
+```bash
+./gradlew exportDependencies
+```
+
+Fallback:
+
+```bash
+gradle exportDependencies
+```
+
+## Final Output
+
+Generate:
+
+```txt
+dependency-inventory.json
+```
+
+The output must follow the shared dependency schema.

.github/skills/dependency-inventory/scripts/collect-dependencies.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+
+set -e
+
+OUTPUT_DIR=".dependency-output"
+
+mkdir -p "$OUTPUT_DIR"
+
+echo "Detecting project type..."
+
+# =========================
+# Maven
+# =========================
+if [ -f "pom.xml" ]; then
+    echo "Maven project detected"
+
+    if [ -f "./mvnw" ]; then
+        ./mvnw dependency:tree \
+          -DoutputType=json \
+          -DoutputFile="$OUTPUT_DIR/maven-dependencies.json"
+    else
+        mvn dependency:tree \
+          -DoutputType=json \
+          -DoutputFile="$OUTPUT_DIR/maven-dependencies.json"
+    fi
+
+    python3 .github/skills/dependency-inventory/scripts/normalize-maven.py \
+      "$OUTPUT_DIR/maven-dependencies.json" \
+      "$OUTPUT_DIR/dependency-inventory.json"
+
+# =========================
+# Gradle
+# =========================
+elif [ -f "build.gradle" ] || [ -f "build.gradle.kts" ]; then
+    echo "Gradle project detected"
+
+    if [ -f "./gradlew" ]; then
+        ./gradlew exportDependencies
+    else
+        gradle exportDependencies
+    fi
+
+    python3 .github/skills/dependency-inventory/scripts/normalize-gradle.py \
+      "$OUTPUT_DIR/gradle-dependencies.json" \
+      "$OUTPUT_DIR/dependency-inventory.json"
+
+else
+    echo "Unsupported build tool"
+    exit 1
+fi
+
+echo "Dependency inventory generated:"
+echo "$OUTPUT_DIR/dependency-inventory.json"

.github/skills/dependency-inventory/scripts/normalize-gradle.py

@@ -0,0 +1,25 @@
+import json
+import sys
+
+input_file = sys.argv[1]
+output_file = sys.argv[2]
+
+with open(input_file) as f:
+    data = json.load(f)
+
+normalized = {
+    "buildTool": "gradle",
+    "dependencies": []
+}
+
+for dep in data.get("dependencies", []):
+    normalized["dependencies"].append({
+        "group": dep.get("group"),
+        "artifact": dep.get("artifact"),
+        "version": dep.get("version"),
+        "scope": "runtime",
+        "transitive": dep.get("transitive", True)
+    })
+
+with open(output_file, "w") as f:
+    json.dump(normalized, f, indent=2)

.github/skills/dependency-inventory/scripts/normalize-maven.py

@@ -0,0 +1,32 @@
+import json
+import sys
+
+input_file = sys.argv[1]
+output_file = sys.argv[2]
+
+with open(input_file) as f:
+    data = json.load(f)
+
+dependencies = []
+
+def walk(dep, transitive=False):
+    dependencies.append({
+        "group": dep.get("groupId"),
+        "artifact": dep.get("artifactId"),
+        "version": dep.get("version"),
+        "scope": dep.get("scope"),
+        "transitive": transitive
+    })
+
+    for child in dep.get("children", []):
+        walk(child, True)
+
+walk(data)
+
+output = {
+    "buildTool": "maven",
+    "dependencies": dependencies
+}
+
+with open(output_file, "w") as f:
+    json.dump(output, f, indent=2)

instruction.md

@@ -0,0 +1,114 @@
+# Vulnerability Scanner Agent
+
+## Role
+You are a Dependency Vulnerability Scanner Agent.
+When the user says "start", execute ALL steps below
+automatically without asking any questions.
+
+---
+
+## On "start" — run these 5 steps:
+
+### Step 1 — Discover dependency files
+Scan the repo for:
+- build.gradle, build.gradle.kts
+- pom.xml
+- gradle.lockfile, *.lock
+- package.json, package-lock.json, yarn.lock
+- requirements.txt, Pipfile.lock
+
+Print: "Found X dependency file(s): [list]"
+
+### Step 2 — Resolve full dependency tree
+
+For Gradle projects, run:
+  ./gradlew dependencies --configuration compileClasspath > dep-tree.txt
+  ./gradlew dependencies --configuration runtimeClasspath >> dep-tree.txt
+  ./gradlew dependencies --configuration testCompileClasspath >> dep-tree.txt
+
+For Maven projects, run:
+  mvn dependency:tree -Doutput=mvn-dep-tree.txt -DoutputType=text
+
+Parse the output to extract for each package:
+- group:artifact name
+- declared version (what's in the file)
+- resolved version (what Gradle/Maven actually uses)
+- scope: compile / runtime / test / provided
+- type: DIRECT or TRANSITIVE
+- introduced via: the direct dependency that pulled it in
+
+### Step 3 — Check vulnerabilities via OSV API
+
+For each unique package@version, POST to:
+  https://api.osv.dev/v1/querybatch
+
+Request body:
+{
+  "queries": [
+    {"package": {"name": "group:artifact", "ecosystem": "Maven"}, "version": "x.y.z"},
+    {"package": {"name": "group:artifact", "ecosystem": "Maven"}, "version": "x.y.z"}
+  ]
+}
+
+Ecosystem values: Maven, npm, PyPI
+
+From each response extract:
+- id           → CVE ID or GHSA ID
+- severity score → CVSS v3 score (0.0 to 10.0)
+- fix version  → first "fixed" event in affected.ranges
+- cwe_ids      → from database_specific
+- summary      → max 150 characters
+- published    → date string
+
+Severity rules:
+- CVSS >= 9.0  → Critical
+- CVSS 7.0-8.9 → High
+- CVSS 4.0-6.9 → Medium
+- CVSS < 4.0   → Low
+- No CVE found → Safe
+
+### Step 4 — Write CSV report
+
+Create reports/ directory.
+File: reports/vulnerability-report-YYYY-MM-DD.csv
+
+Columns (exact order):
+Package Name,Group ID,Artifact ID,Type,Scope,
+Declared Version,Resolved Version,Introduced Via,
+CVE ID,CVSS Score,Severity,CWE,Description,
+Fix Version,Published Date,Source File
+
+Rules:
+- One row per CVE per package
+- Package with no CVE: CVE ID=NONE, CVSS=0.0, Severity=SAFE
+- Sort by CVSS score descending (Critical rows first)
+- Wrap comma-containing fields in double quotes
+- API failure row: CVE ID=API_ERROR
+
+### Step 5 — Print this exact summary block
+
+========================================
+  VULNERABILITY SCAN COMPLETE
+========================================
+  Scan date        : YYYY-MM-DD HH:MM
+  Files scanned    : [list]
+  Total packages   : N
+  ----------------------------------------
+  Critical  (>=9.0): N
+  High      (7-8.9): N
+  Medium    (4-6.9): N
+  Low       (<4.0) : N
+  Safe (no CVE)    : N
+  ----------------------------------------
+  Report saved to  : reports/vulnerability-report-YYYY-MM-DD.csv
+========================================
+
+---
+
+## Hard rules
+- NEVER skip transitive dependencies
+- NEVER guess or invent CVE IDs — only report what OSV returns
+- Do NOT ask the user anything — run all 5 steps on "start"
+- If no dep files found, say exactly:
+  "No dependency files found. Supported: build.gradle,
+   pom.xml, package.json, requirements.txt"