Evidence & AI triage

How each finding gets its verdict, what the AI is and isn't allowed to do, and how accuracy is measured.

#The pipeline for one finding

1. AST context and data flow. SecureSense parses your Python code, finds the enclosing function and the exact flagged statement, and follows the data into the dangerous call: where it comes from, what it passes through, and who calls the function.
2. Five evidence checks (below) run on that context.
3. A bounded loop re-runs any check that failed for a transient reason (e.g. the CVE database was unreachable), at most 3 rounds.
4. Synthesis turns the evidence into a classification, a rationale, and a priority score.

#The five evidence checks

#How the data flow works

For every finding, SecureSense traces what reaches the dangerous argument of the flagged call: the query in cursor.execute(query, params) (not the parameters), the command in subprocess.run(cmd, shell=True), the path in open(path), the URL in requests.get(url).

Sources (user input):

• Flask, Bottle and Quart request.*;
• Django request.GET / POST / body / FILES / … (also self.request in class-based views);
• FastAPI / Starlette Request objects;
• route-handler parameters (URL path and query values), except dependencies injected with Depends(...);
• input() and sys.argv.

Environment variables are tracked too, but as configuration, never as attacker input.

What the trace follows: assignments, f-strings, concatenation, % and .format(), containers, loops (tags.append(t)), comprehensions and both sides of if / else.

Sanitisers count only on the data's path, and only for the weakness they address. An int() applied to a different variable doesn't protect the query, and HTML escaping doesn't stop SQL injection. If the data is sanitised on one branch but not another, the unsanitised path still counts.

Validation guards protect the code after them when they stop execution (abort(), return, raise):

• if col not in ALLOWED: abort(400)
• if not re.fullmatch(...)
• if not value.isdigit()
• assert value in (...)
• if not path.startswith(BASE_DIR)
• an HMAC signature check (hmac.compare_digest) on the request body.

A check that only logs and carries on doesn't count, and neither does startswith("/"), since //evil.example passes it. Looking a value up in a constant table (SORT_COLUMNS.get(choice, "name")) gives the table's value, never the user's key.

Across functions: helpers are summarised, so as_int(v) returning int(v) is recognised as a sanitiser. When a parameter reaches the dangerous call, SecureSense follows the function's callers (up to 3 levels) to see what they pass in.

What it never dismisses:

• Data read back from a database (fetchone() and similar) or fetched over HTTP stays undecided, because it could be second-order injection.
• A finding CodeQL reported is never dismissed just because SecureSense found no source, since CodeQL traced one SecureSense may not know.

The analysis is static and per finding: dynamic dispatch, global state and data stored then read back elsewhere (cache, files) aren't followed.

#The four verdicts

#Who decides: rules, not the AI

The benchmark (below) showed that a small language model deciding on its own ignored clear mitigation evidence and even dismissed a real vulnerability. So in SecureSense:

• Deterministic rules make the keep / dismiss decision from the evidence above.
• The language model only writes the explanation — in plain English, citing the checks it relies on.
• For findings the rules leave Inconclusive, the model may raise the verdict to Likely or Confirmed. It can never dismiss a finding.
• Its answer must fit a strict JSON schema restricted to the verdicts it's allowed to give; anything else is rejected and the rules' own explanation is used.
• Any model error, timeout or rate limit falls back to the rules — the verdict's model field always shows what produced it (rules-v1, hybrid:groq:…).

#Fact-checking the explanation

The rules keep the model away from the decision, but its explanation is still free text, and a language model can make things up. So every explanation is checked against the evidence before you see it:

A sentence counts as a claim only when it states something outright, so hedged wording ("it should be validated", "if the input were escaped…") is never rejected.

When an explanation fails, the model gets one retry with the problems listed. If the retry fails too, SecureSense uses the rules' verdict and explanation, and the model's request to raise an Inconclusive finding is dropped, because an explanation that failed the check can't justify a higher verdict. The dashboard shows the outcome under each explanation (Fact-checked, corrected on the second try, or failed the fact-check). Hover over it to see what was wrong.

On the 26-case benchmark with Groq gpt-oss-20b, 4 of 26 first explanations failed the check (3 cited no evidence; 1 said no user input reached the code when the data flow had been traced), and all 4 passed on the retry. The rules' own explanations all pass, so the checker doesn't flag correct text.

#Choosing a model

For a cloud provider, run SecureSense: Set API Key — the key is stored in your OS keychain. Cloud mode sends the flagged function and its evidence to that provider (Privacy & data).

#Priority score

priority = verdict weight × severity weight × agreement multiplier

The agreement multiplier is 1.5 when both scanners reported the finding, otherwise 1. A confirmed, critical, two-scanner finding scores 3 × 3 × 1.5 = 13.5.

#Benchmark

SecureSense ships a regression benchmark: 44 hand-labelled findings (21 real vulnerabilities, 23 false alarms) in small Flask, FastAPI and Django apps, including deliberately hard cases. A finding counts as kept unless it's called a likely false positive, so:

• Recall = real vulnerabilities kept (never dismissed),
• Precision = kept findings that are real,
• False-positive rate = false alarms still left for a human.

Set 2 (18 cases) was added with the data-flow engine. It tests what a per-function check gets wrong:

• a sanitiser applied to a different variable;
• a guard that only logs;
• sanitisation on one branch only;
• the wrong sanitiser for the weakness;
• input arriving two calls away;
• FastAPI parameters and Django class-based views;
• a weak startswith("/") redirect check.

The data-flow engine first scored 14 of the 18 new cases (it dismissed one real injection built in a loop). The fixes are described in the progress log.

Something unclear or wrong? Edit these docs on GitHub.