Onlock Security Copilot

This workspace now contains two local development targets:

• A starter Visual Studio Code extension built with the official TypeScript generator
• A simple Express server with a POST /analyze endpoint

Open docs/index.html for the simple product page, including the headline, product overview, demo GIF, and install instructions. Use docs/clarity-test-guide.md for a quick message-clarity test with real users, and docs/user-testing-kit.md to run developer feedback sessions.

VS Code Extension

This extension now points to the hosted API at https://developer-security-copilot.onrender.com for scanning, explanations, and fix generation.

Available Commands

• Onlock Security Copilot: Hello World
• Onlock Security Copilot: Test Activation

Test Activation is the quickest smoke test. It activates the extension, writes a timestamped message to the Onlock Security Copilot output channel, and shows a notification in VS Code.

Auto Scan

After activation, the extension now scans the current file automatically when you type and when you save. Typing-triggered scans are lightly debounced, scan requests time out instead of hanging indefinitely, and scan results are written to the Onlock Security Copilot output channel.

When a vulnerability is found, the extension also:

• highlights the vulnerable line in the editor
• adds a warning diagnostic on that line
• shows a warning message for SQL Injection findings
• adds a CodeLens above the line so you can click to view the explanation and suggested fix in a side panel
• lets you click Apply Suggested Fix in that side panel to replace the vulnerable code
• lets you click Send Feedback in that side panel to rate the explanation or fix and add an optional note

Running Locally

1. Open this folder in Visual Studio Code.
2. Press F5 to start the Extension Development Host.
3. In the new window, open or edit a file and watch the Onlock Security Copilot output channel for scan activity.
4. If the first request is slow, the hosted Render service may still be waking up.

Express Server

Run the Server

The extension uses the hosted API by default, so you do not need to run the backend locally just to use the extension.

1. Run npm start.
2. The local development API will start on http://localhost:3000.
3. Opening http://localhost:3000/ in a browser returns a small JSON overview of the local API.

Render Hosting Notes

The backend now includes CORS and OPTIONS preflight handling so hosted browser clients can call the Render deployment directly. It also exposes:

• GET /health for simple hosting health checks
• CORS_ALLOWED_ORIGINS for restricting allowed browser origins when you do not want wildcard access

If CORS_ALLOWED_ORIGINS is not set, the API allows cross-origin requests from any origin by default.

Logging

The backend now writes usage and error logs to both:

• the server console
• logs/server-events.jsonl
• logs/feedback-events.jsonl for saved user feedback

Each log line is JSON and includes a timestamp, level, event name, message, and structured metadata. Scan logging records:

• incoming scan requests
• detected vulnerabilities
• invalid requests
• runtime errors

Feedback storage records:

• whether the explanation or fix felt helpful
• the vulnerability name, severity, file path, and line when available
• an optional free-form comment from the user

LLM Provider Setup

The server now loads .env automatically on startup via dotenv. A sample file is available at .env.example.

• LLM_PROVIDER=mock for local testing without an API call
• LLM_PROVIDER=anthropic with ANTHROPIC_API_KEY and optional ANTHROPIC_MODEL
• LLM_PROVIDER=openai with OPENAI_API_KEY and OPENAI_MODEL
• LLM_PROVIDER=openrouter with OPENROUTER_API_KEY and OPENROUTER_MODEL
• optional LLM_TIMEOUT_MS to control how long the backend waits for a live provider before falling back

Analyze Endpoint

• Method: POST
• URL: https://developer-security-copilot.onrender.com/analyze
• Response schema: schemas/analyze-response.schema.json
• Body:

{
  "text": "const sql = \"SELECT * FROM users WHERE username = '\" + req.query.username + \"'\";"
}

Example response:

{
  "findings": [
    {
      "vulnerability": "SQL Injection",
      "severity": "High",
      "message": "SQL statement concatenates a variable that originated from request input. SQL statement is built with string concatenation and a dynamic value.",
      "line": 2
    }
  ]
}

Each finding now uses the same backend format: vulnerability, severity, message, and line.

Explain Endpoint

• Method: POST
• URL: https://developer-security-copilot.onrender.com/explain
• Body:

{
  "vulnerability": "SQL Injection",
  "code": "const sql = \"SELECT * FROM users WHERE id = '\" + req.query.id + \"'\";"
}

Example response:

{
  "explanation": "SQL Injection happens because this code appears to mix untrusted input directly into a SQL query...",
  "suggestedCode": "const sql = \"SELECT * FROM users WHERE id = ?\";\ndb.query(sql, [req.query.id]);"
}

The explanation prompt sends the vulnerability name and the code snippet to the configured provider, asks for JSON, parses the AI response, and returns both human-readable explanation text and a secure code suggestion.

If the live provider times out, returns empty content, or returns invalid JSON, the backend falls back to a local explanation and secure fix suggestion instead of failing hard.

Feedback Endpoint

• Method: POST
• URL: https://developer-security-copilot.onrender.com/feedback
• Body:

{
  "source": "explanation_panel",
  "rating": "helpful",
  "vulnerability": "SQL Injection",
  "severity": "High",
  "line": 12,
  "filePath": "src/example.py",
  "comment": "The fix suggestion was clear and easy to apply."
}

Example response:

{
  "feedbackId": "feedback-1234567890-abcd1234",
  "storedAt": "2026-03-18T18:40:00.000Z",
  "message": "Feedback stored successfully."
}

Postman

Import postman/onlock-security-copilot.postman_collection.json into Postman and run the Analyze Text or Explain Vulnerability request.

Packaging

• npm run package:vsix builds a local .vsix package in the repository root.
• npm run test:install-vsix installs the latest .vsix into an isolated local VS Code profile to verify the package is installable.

Development

• npm run compile builds the TypeScript sources.
• npm run lint runs ESLint.
• npm run test:explain verifies the /explain endpoint in mock mode, including AI-response parsing.
• npm run test:feedback verifies the /feedback endpoint and JSONL storage.
• npm run test:cors verifies CORS preflight handling and the health endpoint for hosted deployments.
• npm run test:resilience verifies malformed JSON handling plus empty and timed-out provider fallbacks.
• npm test launches the VS Code extension test runner.