🛠️ Custom Plugins Development

This guide explains how to send your security scan data (from tools like Nessus, OpenVAS, or CIS Benchmarks) into ThreatVault. It’s written simply — even non-technical users can follow it.

You’ll learn:

• The difference between VAPT and Compliance data

• Which fields ThreatVault expects

• How to map your tool’s data

• Example plugins you can use

---

🧩 What Is a Plugin?

A plugin is a small Python module that transforms your uploaded scan file (usually CSV) into a format ThreatVault understands.

Workflow:

1. You upload a CSV/JSON scan file.

2. ThreatVault calls your plugin’s process() function.

3. The plugin converts your data into the required schema.

4. ThreatVault validates the output and saves your findings.

---

🔁 Two Types of Data

Type	What It Does	Example
VAPT	Finds vulnerabilities (bugs, weak configurations)	“TLS 1.0 is enabled”
Compliance	Checks if rules or policies are followed	“Password must be 8+ chars — ❌ FAILED”

Quick rules:

• VAPT: “What’s broken?” → Use risk (Critical, High…)

• Compliance: “Did we follow the rule?” → Use status (PASSED, FAILED)

---

🧭 ThreatVault Field Requirements

1️⃣ VAPT (Vulnerability Scan) Fields

Used for tools like Nessus, OpenVAS, Invicti:

{
  "cve": "CVE-2023-1234",      
  "risk": "High",              
  "host": "10.0.0.5",          
  "port": 443,                  
  "name": "TLS 1.0 Enabled",    
  "description": "TLS 1.0 is old and insecure...",  
  "remediation": "Upgrade to TLS 1.2 or higher",     
  "evidence": "Service: https", 
  "vpr_score": "8.2"            
}

• ✅ Required: risk, host, port, name, description, remediation

• 🔹 Optional: cve, evidence, vpr_score

---

2️⃣ Compliance (Rule Check) Fields

Used for CIS, ISO 27001, and internal policy checks:

{
  "risk": "High",              
  "host": "webserver01",       
  "port": 0,                    
  "name": "Password Length ≥ 8",
  "description": "Must enforce 8+ characters",
  "remediation": "Set min length to 8",
  "evidence": "Current: 6",     
  "status": "FAILED"            
}

• ✅ Required: risk, host, port, name, description, remediation, status

• 🔹 Optional: evidence

Notes:

• Nessus compliance scans don’t use severity levels. risk values are mapped to status.

• If risk is empty, the plugin assigns Medium automatically.

• cve and vpr_score are not used for compliance scans.

---

🗺️ Mapping Scan Data to ThreatVault

Source Field	→	ThreatVault Field	Notes
Risk	→	risk	Use Critical/High/Medium/Low. Leave empty for compliance → auto Medium
Host	→	host	IP or hostname
Port	→	port	Use 0 if not applicable
Name	→	name	Issue title
Description	→	description	Full explanation
Solution	→	remediation	How to fix
Plugin Output / Actual Value	→	evidence	Proof from scan
VPR Score	→	vpr_score	Only for VAPT
(none)	→	status	Only for Compliance (copy from risk)

---

🧩 Real Examples

🔹 VAPT Scan (Nessus)

CSV Header: CVE,Risk,Host,Port,Name,Description,Solution,Plugin Output,VPR Score

Mapped to ThreatVault JSON:

{
  "cve": "",
  "risk": "High",
  "host": "10.0.0.5",
  "port": 443,
  "name": "TLS 1.0 Enabled",
  "description": "Old protocol...",
  "remediation": "Upgrade TLS",
  "evidence": "Service: https",
  "vpr_score": "8.2"
}

---

🔹 Compliance Scan (Nessus)

CSV Header: CVE,Risk,Host,Port,Name,Description,Solution,Plugin Output,VPR Score

Mapped to ThreatVault JSON:

{
  "risk": "High",
  "host": "db01",
  "port": 0,
  "name": "Password Reuse Disabled",
  "description": "Must block reuse of last 5 passwords",
  "remediation": "Set to 5",
  "evidence": "Current: 0",
  "status": "FAILED"
}

---

✅ Acceptable Values

Risk (Severity)

Value	Notes
CRITICAL	Only for VAPT
HIGH	Both
MEDIUM	Both
LOW	Both
None	Only Compliance → auto Medium

Status

Scan Type	Allowed Values
VAPT	NEW, OPEN, CLOSED, EXEMPTION, OTHERS
Compliance	PASSED, FAILED, WARNING

---

🧰 Plugin Examples

1️⃣ Compliance Plugin (Python + Polars)

import polars as pl

def process(file: bytes, file_type: str) -> pl.LazyFrame:
    if file_type != "text/csv":
        raise ValueError(f"File type not supported: {file_type}")

    pattern2 = r"Actual Value:\s*\n(?s)(.*)"
    lf = pl.scan_csv(file)
    lf = (
        lf.with_columns(
            name=pl.col("Description").str.extract(r"^(.*): \[.*\]", 1),
            description=pl.col("Description")
                .str.extract(r"^(?:.*\n){2}((?s).*?)(?:^Actual Value:|$)", 1)
                .str.replace(pattern2, "")
                .str.replace_all("\n", "<br/>"),
            evidence=pl.col("Description")
                .str.extract(pattern2)
                .str.replace_all("\n", "<br/>")
                .str.strip_chars(),
            risk=pl.lit(None, dtype=pl.String),
        )
        .filter(pl.col("Risk") != "None", pl.col("Risk").is_not_null())
        .rename({"Solution": "remediation", "Risk": "status"})
        .drop(["VPR Score", "CVE", "Name", "Plugin Output", "Description"])
    )
    return lf

---

2️⃣ VAPT Plugin (Python + Polars)

import polars as pl

def process(file: bytes, file_type: str) -> pl.LazyFrame:
    if file_type != "text/csv":
        raise ValueError(f"File type not supported: {file_type}")

    return (
        pl.scan_csv(file)
        .select(pl.all().name.map(lambda x: "_".join(x.lower().split(" "))))
        .filter(pl.col("risk") != "None")
        .with_columns(
            pl.col("solution", "description", "plugin_output").str.replace_all(
                "\n", " <br/> "
            )
        )
        .rename(
            {
                "solution": "remediation",
                "plugin_output": "evidence",
            }
        )
    )

---

🚀 Quick Steps to Build Your Plugin

1. Decide: VAPT or Compliance

2. Read your CSV/JSON file

3. Rename columns to match ThreatVault

4. Fill in required fields

5. For Compliance (Nessus): status = risk

6. Remove unused fields (e.g., cve in Compliance)

7. Return Polars LazyFrame or DataFrame

8. Upload to ThreatVault → Test → Done

---

🏁 Summary Table

Field	VAPT	Compliance
cve	✅	❌
risk	✅	✅
status	❌	✅
host	✅	✅
port	✅	✅
name	✅	✅
description	✅	✅
remediation	✅	✅
evidence	✅	✅
vpr_score	✅	❌