koda-waf-2

Koda WAF 2

Koda WAF 2 is an experimental AI-assisted Web Application Firewall classifier for HTTP request analysis. It classifies request-like inputs as benign or malicious.

Repository:

https://huggingface.co/netgoat-ai/koda-waf-2

Current artifact:

koda_waf_2_advanced.joblib

What This Model Expects

The model was trained on structured HTTP request fields:

method
path
query
headers
body

For the advanced model, inference expects a pandas DataFrame with those columns.

Install

pip install huggingface_hub joblib pandas scikit-learn

Load From Hugging Face

import joblib
import pandas as pd
from huggingface_hub import hf_hub_download


model_path = hf_hub_download(
    repo_id="netgoat-ai/koda-waf-2",
    filename="koda_waf_2_advanced.joblib",
)

payload = joblib.load(model_path)
model = payload["model"]

request = pd.DataFrame(
    [
        {
            "method": "GET",
            "path": "/api/search",
            "query": "q=' OR '1'='1",
            "headers": "user-agent:test-client",
            "body": "",
        }
    ]
)

label = model.predict(request)[0]
classes = list(model.classes_)
probabilities = model.predict_proba(request)[0]

print("label:", label)
print(dict(zip(classes, probabilities)))

Example Inputs

Benign-looking request:

{
    "method": "GET",
    "path": "/api/search",
    "query": "q=laptop&page=1",
    "headers": "user-agent:browser accept:application/json",
    "body": "",
}

Suspicious request:

{
    "method": "GET",
    "path": "/api/search",
    "query": "q=' OR '1'='1",
    "headers": "user-agent:test-client",
    "body": "",
}

Evaluation Snapshot

Local held-out CSV evaluation for koda_waf_2_advanced.joblib:

accuracy: 0.9853

benign     precision 1.00  recall 0.98  f1 0.99
malicious  precision 0.97  recall 1.00  f1 0.98

Local test split size:

15,000 rows
8,801 benign
6,199 malicious

Important Safety Note

This repository uses a .joblib model artifact. Joblib uses Python pickle under the hood, and pickle files can execute code when loaded. Only load this model if you trust the repository and artifact.

Hugging Face may show security warnings for pickle/joblib artifacts. That is expected for this file type and should be taken seriously.

Limitations

• This is a prototype defensive classifier, not a complete production WAF.
• The model should be validated against your own real benign and malicious traffic before deployment.
• It can produce false positives on unusual but benign request text.
• It can miss attacks that are outside the training distribution.
• Do not use it as the only security control for production systems.

Intended Use

Good uses:

• Local WAF research
• Defensive traffic classification experiments
• Comparing model behavior against labeled HTTP request datasets
• Building a broader WAF pipeline with rules, logging, and human review

Do not use:

• As a standalone production security boundary
• On systems you do not own or have permission to test
• With datasets containing real secrets, cookies, passwords, tokens, or private user data

License

MIT License.