Pysa JSON Models

Pysa JSON Model Syntax

Overview

Pysa outputs analysis results as newline-delimited JSON (NDJSON). Each line is a self-contained JSON object with "kind" and "data" fields. There are two kinds: "model" (a callable's taint behavior) and "issue" (a detected vulnerability).

Top-Level Wrapper

Every JSON object is wrapped as:

{"kind": "model", "data": { ... }}
{"kind": "issue", "data": { ... }}

Models and issues are separate top-level objects. Issues are never nested inside models.

Model Structure

{
  "callable": "module.function_name",
  "filename": "module.py",
  "callable_line": 42,
  "sources": [ ... ],
  "sinks": [ ... ],
  "tito": [ ... ],
  "parameter_sources": [ ... ],
  "global_sanitizer": { ... },
  "parameters_sanitizer": { ... },
  "sanitizers": [ ... ],
  "modes": [ "Obscure", ... ]
}

All fields except callable are optional. Empty fields are omitted entirely — never include empty arrays [] or objects {}.

Note: "sources" represents generations (taint produced by the function). This is distinct from "parameter_sources" which represents sources on parameters.

Callables

• Regular functions: "module.function_name"
• Methods: "module.ClassName.method_name"
• Attribute models: "Obj{module.ClassName.attribute_name}"

Modes

Available modes: Obscure, SkipObscure, SkipAnalysis, SkipOverrides, AnalyzeAllOverrides, Entrypoint, IgnoreDecorator, SkipModelBroadening, InferSelfTito, InferArgumentTito.

Port Entries (sources/sinks/tito/parameter_sources)

Each of sources, sinks, tito, and parameter_sources is a list of port entries:

{
  "port": "<port>",
  "taint": [ <trace_element>, ... ]
}

Port Formats

Key rule: position is always included in formal() ports (e.g., formal(x, position=0), not formal(x)).

For sources/parameter_sources, the port indicates where taint is produced (typically result or result[field]).

For sinks, the port indicates where taint is consumed (typically formal(...) with optional access path).

For tito, the port indicates the input side (always formal(...)). The output side is encoded inside the taint entry via return_paths.

Trace Elements (Call Info)

Each element in a "taint" list is a trace element keyed by its call info. There are four call info variants:

1. Declaration — user-specified taint from .pysa model files

{
  "kinds": [ { "kind": "Test" } ],
  "declaration": null
}

This is the leaf of the trace — the taint is directly declared by the user, not propagated from another function.

2. Origin — taint at a direct call site (first hop)

{
  "kinds": [ { "kind": "Test", "length": 0 } ],
  "origin": { "line": 16, "start": 15, "end": 20 }
}

Represents a call to a function with a user-declared model. The origin location is where the call happens. "call_site" may also be present (e.g., "call_site": "16:4-16:21").

3. Call — taint propagated through a call chain

{
  "kinds": [ { "kind": "Test", "length": 2 } ],
  "call": {
    "position": { "line": 20, "start": 8, "end": 22 },
    "resolves_to": [ "module.callee_function" ],
    "port": "result[a]"
  }
}

Represents a hop: taint flows from callee_function at the given port. resolves_to is a list (can have multiple callees for overrides). "call_site" may also appear inside the "call" object.

4. Tito — taint-in-taint-out propagation

{
  "kinds": [ { "return_paths": { "": 0 }, "kind": "LocalReturn" } ],
  "tito": {}
}

Used in "tito" port entries. The "tito" call info is always {} (empty object, never null).

Kind Entries

Each "kinds" list entry describes a taint kind with optional metadata:

{
  "kind": "Test",
  "length": 2,
  "leaves": [ { "name": "pysa._test_source", "port": "leaf:return" } ],
  "features": [ { "always-via": "special_source" } ],
  "local_features": [ { "always-via": "special_sink" } ],
  "return_paths": { "": 0 }
}

Leaf Ports

• leaf:return — source on return value
• leaf:arg — sink on argument
• leaf:arg[field] — sink on argument field
• producer:N:formal(M) — cross-repository producer
• anchor:formal(M) — cross-repository anchor

Trace-Level Local Features and Tito Positions

Local features and tito positions can appear at the trace element level (outside kinds):

{
  "kinds": [ ... ],
  "local_features": [ { "has": "first-index" }, { "first-index": "<numeric>" } ],
  "tito_positions": [ { "line": 71, "start": 34, "end": 37 } ],
  "origin": { ... }
}

local_features (trace-level): Breadcrumbs introduced at this particular call site within the current function. These describe what happens to the data at this point in the flow — for example, first-index records the first dictionary key or list index used to access tainted data. Unlike kind-level local_features (which are specific to a taint kind), trace-level local features apply across all kinds in the trace element.

tito_positions: Locations in the current function where taint was propagated via taint-in-taint-out. Each entry is a source position (line, start, end) pointing to an expression where tainted data flowed through a TITO function call. This helps trace how data moved through the function before reaching a sink or being returned.

Features (Breadcrumbs)

Features use a prefix to indicate whether they appear on all paths (always-) or some paths (no prefix):

{ "always-via": "special_source" }
{ "via": "tito" }
{ "always-type": "bool" }
{ "has": "first-index" }
{ "first-index": "<numeric>" }
{ "first-index": "arg" }
{ "has": "first-field" }
{ "first-field": "attribute_name" }

Sanitizers

Global Sanitizer (applies to entire function)

"global_sanitizer": {
  "sources": "All",
  "sinks": [ "SQL" ],
  "tito": { "sources": [ "UserControlled" ], "sinks": "All" }
}

Each of sources, sinks, tito is optional. Values are either "All" or a list of kind names. The tito sub-object has its own sources/sinks.

Parameters Sanitizer (applies to all parameters)

Same format as global sanitizer, under key "parameters_sanitizer".

Per-Root Sanitizers

"sanitizers": [
  {
    "port": "formal(x, position=0)",
    "sources": "All",
    "sinks": [ "TestSink" ]
  }
]

Issue Structure

Issues are separate top-level objects, not nested inside models:

{
  "kind": "issue",
  "data": {
    "callable": "module.function_name",
    "callable_line": 19,
    "code": 5002,
    "line": 21,
    "start": 15,
    "end": 16,
    "filename": "module.py",
    "message": "Data from [Test] source(s) may reach [Test] sink(s)",
    "traces": [
      {
        "name": "forward",
        "roots": [ <trace_elements> ]
      },
      {
        "name": "backward",
        "roots": [ <trace_elements> ]
      }
    ],
    "features": [ { "always-via": "special_source" } ],
    "sink_handle": {
      "kind": "Call",
      "callee": "module.sink_function",
      "index": 0,
      "parameter": "formal(arg)"
    },
    "master_handle": "module.function:5002:0:Call|module.sink|0|formal(arg):md5hash"
  }
}

Trace elements in roots use the same format as model trace elements (kinds/call/origin/declaration).

Sink Handle Variants

parameter in sink handle uses the callee's parameter name (e.g., formal(arg) for _test_sink(arg)), not the caller's argument variable name.

Common Mistakes

Complete Example

Given:

# example.py
from pysa import _test_source, _test_sink

def get_source():
    return _test_source()

def flow():
    x = get_source()
    _test_sink(x)

Model for _test_source (user-declared source):

{
  "kind": "model",
  "data": {
    "callable": "pysa._test_source",
    "filename": "pysa/__init__.pyi",
    "callable_line": 5,
    "sources": [
      {
        "port": "result",
        "taint": [
          {
            "kinds": [
              {
                "features": [ { "always-via": "special_source" } ],
                "kind": "Test"
              }
            ],
            "declaration": null
          }
        ]
      }
    ],
    "modes": [ "Obscure" ]
  }
}

Model for get_source (inferred source via call):

{
  "kind": "model",
  "data": {
    "callable": "example.get_source",
    "filename": "example.py",
    "callable_line": 4,
    "sources": [
      {
        "port": "result",
        "taint": [
          {
            "kinds": [
              {
                "local_features": [ { "always-via": "special_source" } ],
                "leaves": [ { "name": "pysa._test_source", "port": "leaf:return" } ],
                "kind": "Test"
              }
            ],
            "origin": { "line": 5, "start": 11, "end": 25 }
          }
        ]
      }
    ]
  }
}

Issue for flow:

{
  "kind": "issue",
  "data": {
    "callable": "example.flow",
    "callable_line": 7,
    "code": 5002,
    "line": 9,
    "start": 15,
    "end": 16,
    "filename": "example.py",
    "message": "Data from [Test] source(s) may reach [Test] sink(s)",
    "traces": [
      {
        "name": "forward",
        "roots": [
          {
            "kinds": [
              {
                "features": [ { "always-via": "special_source" } ],
                "leaves": [ { "name": "pysa._test_source", "port": "leaf:return" } ],
                "length": 1,
                "kind": "Test"
              }
            ],
            "call": {
              "position": { "line": 8, "start": 8, "end": 20 },
              "resolves_to": [ "example.get_source" ],
              "port": "result"
            }
          }
        ]
      },
      {
        "name": "backward",
        "roots": [
          {
            "kinds": [
              {
                "local_features": [ { "always-via": "special_sink" } ],
                "leaves": [ { "name": "pysa._test_sink", "port": "leaf:arg" } ],
                "kind": "Test"
              }
            ],
            "origin": { "line": 9, "start": 15, "end": 16 }
          }
        ]
      }
    ],
    "features": [
      { "always-via": "special_source" },
      { "always-via": "special_sink" }
    ],
    "sink_handle": {
      "kind": "Call",
      "callee": "pysa._test_sink",
      "index": 0,
      "parameter": "formal(arg)"
    },
    "master_handle": "example.flow:5002:0:Call|pysa._test_sink|0|formal(arg):abcdef1234567890"
  }
}

Reference

• Model types defined in: source/interprocedural_analyses/taint/model.ml
• Call info, frames, taint serialization: source/interprocedural_analyses/taint/domains.ml
• Feature/breadcrumb format: source/interprocedural_analyses/taint/features.ml
• Issue format: source/interprocedural_analyses/taint/issue.ml
• Sanitizer format: source/interprocedural_analyses/taint/sanitize.ml