facebook/pyre-check/pysa-json-models
Claude Code and agent skill by facebook/pyre-check
- community
Checking that the SKILL.md file is still in the repository.
Use when reading, writing, or debugging Pysa JSON model output (.models files). Use when working with taint models that describe sources, sinks, TITO, sanitizers, or issues in JSON format.
Install
npx vskill@latest install facebook/pyre-check/pysa-json-modelsSKILL.md
The same SKILL.md was published earlier as facebook/pyre-check/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:
Models and issues are separate top-level objects. Issues are never nested inside models.
Model Structure
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 Formats
| Port | Meaning | |
|---|---|---|
result | Return value | |
result[field] | Return value with access path | |
formal(name, position=N) | Named parameter at position N | |
formal(name, position=N, positional_only) | Positional-only parameter | |
formal(name, position=N)[field][subfield] | Parameter with access path | |
formal(*args, position=N) | Variadic positional args | |
formal(**kwargs) | Variadic keyword args | |
formal(**kwargs, excluded=[x]) | Kwargs excluding named params | |
formal($global, position=0) | Global/attribute model port |
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
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)
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
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
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:
| Field | Description | |
|---|---|---|
kind | Source/sink kind name (e.g., Test, UserControlled, SQL, RemoteCodeExecution). For TITO: LocalReturn | |
length | Trace length (hops to closest leaf). Omitted when 0 | |
leaves | Set of leaf declarations this taint originates from. Each leaf: {"name": "qualified.name", "port": "leaf:return"} | |
features | Propagated breadcrumbs from callees | |
local_features | Breadcrumbs introduced in this function | |
return_paths | (TITO only) Maps access paths to collapse depths, e.g. {"": 0} (identity), {"[field]": 3} (into field) |
Leaf Ports
leaf:return— source on return valueleaf:arg— sink on argumentleaf:arg[field]— sink on argument fieldproducer:N:formal(M)— cross-repository produceranchor: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):
`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):
Sanitizers
Global Sanitizer (applies to entire function)
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
Issue Structure
Issues are separate top-level objects, not nested inside models:
Trace elements in roots use the same format as model trace elements (kinds/call/origin/declaration).
Sink Handle Variants
| Variant | Fields | |
|---|---|---|
Call | callee, index, parameter | |
Global | callee, index | |
Return | (none) | |
LiteralStringSink | sink | |
ConditionalTestSink | sink | |
StringFormat | callee, index, parameter_index |
`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
| Mistake | Correct | |
|---|---|---|
"formal(x)" | "formal(x, position=0)" — always include position | |
"declaration": {} or "decl": null | "declaration": null — exact key and value matter | |
"tito": null (call info) | "tito": {} — empty object, not null | |
TITO port = "result" | TITO port = "formal(...)" — port is the input side | |
Issues inside model "errors" | Issues are separate {"kind": "issue"} objects | |
Including "sources": [] | Omit empty fields entirely | |
Leaves: {"kind": "Test", "name": "..."} | Leaves: {"name": "pysa._test_source", "port": "leaf:return"} | |
| sink_handle parameter = caller's variable | sink_handle parameter = callee's parameter name |
Complete Example
Given:
Model for _test_source (user-declared source):
Model for get_source (inferred source via call):
This is the start of the file. Read the full SKILL.md on GitHub.
Security
- Security scanPassed, 100 of 100Pattern checks on the skill's files.
- Model reviewNot runA model review is scheduled for the next rescan.
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryChecking.llms/skills/pysa-json-models/SKILL.md
Popularity
- Repository stars
- 7,165
- Repository forks
- 452
- 7-day trend score
- 44
Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/facebook/pyre-check/pysa-json-models)