pyflow-analysis 0.1.0__tar.gz → 0.1.2__tar.gz

pyflow_analysis-0.1.2/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: pyflow-analysis
+Version: 0.1.2
+Summary: A static analysis framework for Python
+Author-email: rainoftime <rainoftime@gmail.com>
+Maintainer-email: rainoftime <rainoftime@gmail.com>
+License: Apache-2.0
+Keywords: python,compiler,static-analysis,optimization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: asciitree
+Requires-Dist: graphviz
+Requires-Dist: networkx
+Requires-Dist: packaging
+Requires-Dist: rstr
+Requires-Dist: typing_inspect
+Provides-Extra: dev
+Requires-Dist: z3-solver; extra == "dev"
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-timeout>=2.3; extra == "dev"
+Requires-Dist: black==26.10.0; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: tomli; python_version < "3.11" and extra == "dev"
+Provides-Extra: test
+Requires-Dist: z3-solver; extra == "test"
+Requires-Dist: pytest>=6.0; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-timeout>=2.3; extra == "test"
+Requires-Dist: tomli; python_version < "3.11" and extra == "test"
+Provides-Extra: callgraph
+Requires-Dist: pycg==0.0.6; extra == "callgraph"
+Provides-Extra: concolic
+Requires-Dist: z3-solver; extra == "concolic"
+Provides-Extra: supply-chain
+Requires-Dist: jsonschema>=4.18; extra == "supply-chain"
+Requires-Dist: sigstore>=3; extra == "supply-chain"
+Dynamic: license-file
+
+
+# PyFlow: Static Analysis for Python
+
+PyFlow is a program analysis framework for Python. It combines
+program analysis infrastructure, experimental optimization passes, and security
+checking in a single research-oriented toolkit.
+
+Current status: **alpha**. The project already contains substantial analysis
+and testing infrastructure, but APIs, pass behavior, and CLI details are still
+evolving.
+
+If you use pyflow in your research or work, please cite the following:
+~~~~
+@misc{pyflow2026,
+  title         = {PyFlow: An Inter-procedural Static Analysis Framework for Python},
+  author        = {Gu, Zinan and Yan, Haoxiang and Yao, Peisen},
+  year          = {2026},
+  eprint        = {2608.07026},
+  archivePrefix = {arXiv},
+  doi           = {10.48550/arXiv.2608.07026},
+  url           = {https://arxiv.org/abs/2608.07026}
+}
+~~~~
+
+
+## What PyFlow includes
+
+- **Intermediate representations**: seven-instruction MIR, CFG, CDG, DDG, PDG,
+  CPG, lowered data flow IR, and a shared store graph model
+- **Program analysis**: call graph, IFDS, alias, IPA, CPA, shape, lifetime,
+  and type-analysis infrastructure
+- **Optimization pipeline**: modular passes such as simplify, method-call
+  optimization, cloning, argument normalization, and load/store elimination
+- **Security checking**: ast pattern, ast-dataflow, cpg, and ifds security analysis
+- **Supply-chain analysis**: local SBOM generation, distribution integrity
+  auditing, and dependency metadata extraction
+- **CLI tooling**: commands for optimization, call graph generation, IR dumps,
+  security, supply-chain, alias analysis, and concolic test-input generation
+
+## Evaluation results
+
+Security analysis engines evaluated on the PySASTBench microbenchmark
+(ICSE 26):
+
+```bash
+python3 evaluation/pysastbench/bench_micro.py --timeout 45 --workers 16
+```
+
+| Engine       | Precision | Recall | F1    | Accuracy |
+|--------------|-----------|--------|-------|----------|
+| ast-scanner  | 0.623     | 0.400  | 0.487 | 0.579    |
+| ast-dataflow | 0.849     | 0.842  | 0.845 | 0.846    |
+| cpg          | 0.792     | 0.792  | 0.792 | 0.792    |
+| ifds         | 0.852     | 0.767  | 0.807 | 0.817    |
+
+## Installation and Usage
+
+### Prerequisites
+- Python 3.10 or newer
+- Graphviz (for visualization features)
+
+### Install from source
+```bash
+git clone https://github.com/ZJU-PL/pyflow.git
+cd pyflow
+pip install -e .
+```
+
+For development, install the dev extras:
+```bash
+pip install -e ".[dev]"
+```
+
+The native MIR-based PyCG algorithm is included in the standard installation.
+If you want the optional upstream PyCG-backed call-graph algorithm, install:
+```bash
+pip install -e ".[dev,callgraph]"
+```
+
+
+### Usage
+
+
+```bash
+# Dump IR for a specific function
+pyflow ir input.py --dump-ast function_name
+
+# Lower source to the seven-instruction MIR without executing the source
+pyflow ir input.py --dump-mir --dump-format json --dump-output out/
+
+# Generate a call graph
+pyflow callgraph input.py
+
+# Generate a native PyCG-style call graph from MIR
+pyflow callgraph input.py --algorithm pycg-mir
+
+# Generate a call graph with the optional upstream PyCG package
+pyflow callgraph input.py --algorithm pycg
+
+# Run security analysis (fast AST scan)
+pyflow security input.py
+
+# Run AST-based interprocedural taint dataflow
+pyflow security input.py --engine ast-dataflow
+
+# Run IFDS-backed interprocedural security analysis
+pyflow security input.py --engine ifds --sources input --sinks eval
+
+# Run CPG-based security analysis
+pyflow security input.py --engine cpg --framework flask
+
+# Run alias analysis (flow-sensitive heap or k-CFA pointer)
+pyflow alias input.py --verbose
+
+# Generate branch-covering integer inputs for a pure function named main
+pyflow concolic input.py --inputs '[0]' --json
+
+# Start the LSP server (Content-Length framed JSON-RPC)
+pyflow lsp --root . --mode full
+
+# Start the MCP server (newline-delimited JSON-RPC over stdio)
+pyflow mcp --root . --mode full
+
+# Run a one-shot semantic query
+pyflow query . --get-callers package.module.function --pretty
+
+# Generate a CycloneDX SBOM from local package metadata
+pyflow supply-chain sbom package/
+```
+
+See [CLI.md](CLI.md) for the command reference,
+[docs/source/ir/mir.rst](docs/source/ir/mir.rst) for MIR, the native PyCG API,
+and implementation limits,
+[docs/source/lsp.rst](docs/source/lsp.rst) for LSP, MCP, and semantic-query
+integration, and `docs/` for broader project
+documentation.
+
+### Running Tests
+
+```bash
+# Run the default unit-focused test suite
+pytest
+
+# Run integration tests explicitly
+pytest -m integration tests/integration
+
+# Run focused areas
+pytest tests/ir
+pytest tests/frontend
+pytest tests/api
+pytest tests/checker
+```

pyflow_analysis-0.1.2/README.md

@@ -0,0 +1,152 @@
+
+# PyFlow: Static Analysis for Python
+
+PyFlow is a program analysis framework for Python. It combines
+program analysis infrastructure, experimental optimization passes, and security
+checking in a single research-oriented toolkit.
+
+Current status: **alpha**. The project already contains substantial analysis
+and testing infrastructure, but APIs, pass behavior, and CLI details are still
+evolving.
+
+If you use pyflow in your research or work, please cite the following:
+~~~~
+@misc{pyflow2026,
+  title         = {PyFlow: An Inter-procedural Static Analysis Framework for Python},
+  author        = {Gu, Zinan and Yan, Haoxiang and Yao, Peisen},
+  year          = {2026},
+  eprint        = {2608.07026},
+  archivePrefix = {arXiv},
+  doi           = {10.48550/arXiv.2608.07026},
+  url           = {https://arxiv.org/abs/2608.07026}
+}
+~~~~
+
+
+## What PyFlow includes
+
+- **Intermediate representations**: seven-instruction MIR, CFG, CDG, DDG, PDG,
+  CPG, lowered data flow IR, and a shared store graph model
+- **Program analysis**: call graph, IFDS, alias, IPA, CPA, shape, lifetime,
+  and type-analysis infrastructure
+- **Optimization pipeline**: modular passes such as simplify, method-call
+  optimization, cloning, argument normalization, and load/store elimination
+- **Security checking**: ast pattern, ast-dataflow, cpg, and ifds security analysis
+- **Supply-chain analysis**: local SBOM generation, distribution integrity
+  auditing, and dependency metadata extraction
+- **CLI tooling**: commands for optimization, call graph generation, IR dumps,
+  security, supply-chain, alias analysis, and concolic test-input generation
+
+## Evaluation results
+
+Security analysis engines evaluated on the PySASTBench microbenchmark
+(ICSE 26):
+
+```bash
+python3 evaluation/pysastbench/bench_micro.py --timeout 45 --workers 16
+```
+
+| Engine       | Precision | Recall | F1    | Accuracy |
+|--------------|-----------|--------|-------|----------|
+| ast-scanner  | 0.623     | 0.400  | 0.487 | 0.579    |
+| ast-dataflow | 0.849     | 0.842  | 0.845 | 0.846    |
+| cpg          | 0.792     | 0.792  | 0.792 | 0.792    |
+| ifds         | 0.852     | 0.767  | 0.807 | 0.817    |
+
+## Installation and Usage
+
+### Prerequisites
+- Python 3.10 or newer
+- Graphviz (for visualization features)
+
+### Install from source
+```bash
+git clone https://github.com/ZJU-PL/pyflow.git
+cd pyflow
+pip install -e .
+```
+
+For development, install the dev extras:
+```bash
+pip install -e ".[dev]"
+```
+
+The native MIR-based PyCG algorithm is included in the standard installation.
+If you want the optional upstream PyCG-backed call-graph algorithm, install:
+```bash
+pip install -e ".[dev,callgraph]"
+```
+
+
+### Usage
+
+
+```bash
+# Dump IR for a specific function
+pyflow ir input.py --dump-ast function_name
+
+# Lower source to the seven-instruction MIR without executing the source
+pyflow ir input.py --dump-mir --dump-format json --dump-output out/
+
+# Generate a call graph
+pyflow callgraph input.py
+
+# Generate a native PyCG-style call graph from MIR
+pyflow callgraph input.py --algorithm pycg-mir
+
+# Generate a call graph with the optional upstream PyCG package
+pyflow callgraph input.py --algorithm pycg
+
+# Run security analysis (fast AST scan)
+pyflow security input.py
+
+# Run AST-based interprocedural taint dataflow
+pyflow security input.py --engine ast-dataflow
+
+# Run IFDS-backed interprocedural security analysis
+pyflow security input.py --engine ifds --sources input --sinks eval
+
+# Run CPG-based security analysis
+pyflow security input.py --engine cpg --framework flask
+
+# Run alias analysis (flow-sensitive heap or k-CFA pointer)
+pyflow alias input.py --verbose
+
+# Generate branch-covering integer inputs for a pure function named main
+pyflow concolic input.py --inputs '[0]' --json
+
+# Start the LSP server (Content-Length framed JSON-RPC)
+pyflow lsp --root . --mode full
+
+# Start the MCP server (newline-delimited JSON-RPC over stdio)
+pyflow mcp --root . --mode full
+
+# Run a one-shot semantic query
+pyflow query . --get-callers package.module.function --pretty
+
+# Generate a CycloneDX SBOM from local package metadata
+pyflow supply-chain sbom package/
+```
+
+See [CLI.md](CLI.md) for the command reference,
+[docs/source/ir/mir.rst](docs/source/ir/mir.rst) for MIR, the native PyCG API,
+and implementation limits,
+[docs/source/lsp.rst](docs/source/lsp.rst) for LSP, MCP, and semantic-query
+integration, and `docs/` for broader project
+documentation.
+
+### Running Tests
+
+```bash
+# Run the default unit-focused test suite
+pytest
+
+# Run integration tests explicitly
+pytest -m integration tests/integration
+
+# Run focused areas
+pytest tests/ir
+pytest tests/frontend
+pytest tests/api
+pytest tests/checker
+```

pyflow_analysis-0.1.2/pyproject.toml

@@ -0,0 +1,152 @@
+# Copyright 2025-2026 rainoftime
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyflow-analysis"
+dynamic = ["version"]
+description = "A static analysis framework for Python"
+readme = "README.md"
+license = {text = "Apache-2.0"}
+authors = [
+    {name = "rainoftime", email = "rainoftime@gmail.com"}
+]
+maintainers = [
+    {name = "rainoftime", email = "rainoftime@gmail.com"}
+]
+keywords = ["python", "compiler", "static-analysis", "optimization"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Compilers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "asciitree",
+    "graphviz",
+    "networkx",
+    "packaging",
+    "rstr",
+    "typing_inspect"
+]
+
+[project.optional-dependencies]
+dev = [
+    "z3-solver",
+    "pytest>=6.0",
+    "pytest-cov",
+    "pytest-timeout>=2.3",
+    "black==26.10.0",
+    "flake8",
+    "mypy",
+    "tomli; python_version < '3.11'"
+]
+# a3-python is a standalone third-party package at third-party/a3_python/.
+# Install it separately: pip install -e third-party/a3_python
+test = [
+    "z3-solver",
+    "pytest>=6.0",
+    "pytest-cov",
+    "pytest-timeout>=2.3",
+    "tomli; python_version < '3.11'",
+]
+callgraph = [
+    "pycg==0.0.6",
+]
+concolic = [
+    "z3-solver",
+]
+supply-chain = [
+    "jsonschema>=4.18",
+    "sigstore>=3",
+]
+
+[project.scripts]
+pyflow = "pyflow.cli.main:entrypoint"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = {attr = "pyflow.__version__"}
+
+[tool.setuptools.package-data]
+pyflow = ["lib/**/*", "stubs/**/*", "config/**/*", "analysis/alias/kcfa/_pythonstan/stubs/**/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test*"]
+norecursedirs = ["tests/full"]
+markers = [
+    "integration: integration tests (CLI, full pipeline); run with -m integration",
+    "slow: slow-running tests excluded from the default fast path by convention",
+]
+addopts = [
+    "--strict-markers",
+    "--strict-config",
+    "--verbose",
+    "-m",
+    "not integration",
+    #"-W", "ignore::DeprecationWarning",
+    "-W",
+    "ignore::pytest.PytestUnhandledThreadExceptionWarning",
+]
+timeout = 120
+timeout_method = "thread"
+
+[tool.black]
+line-length = 100
+target-version = ['py310']
+include = '\.pyi?$'
+extend-exclude = '''
+/(
+  # directories
+  \.eggs
+  | \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | venv
+  | _build
+  | buck-out
+  | build
+  | dist
+  | third-party
+)/
+'''
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+check_untyped_defs = true
+disallow_untyped_decorators = false
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+strict_equality = true
+
+[[tool.mypy.overrides]]
+module = [
+    "antlr3.*",
+    "PADS.*",
+    "pydot",
+]
+ignore_missing_imports = true

pyflow_analysis-0.1.2/src/pyflow/__init__.py

@@ -0,0 +1,5 @@
+"""PyFlow - Static Analysis Framework for Python."""
+
+__version__ = "0.1.2"
+__author__ = "rainoftime"
+__email__ = "rainoftime@gmail.com"

pyflow_analysis-0.1.2/src/pyflow/analysis/__init__.py

@@ -0,0 +1,15 @@
+"""Analysis modules for PyFlow static analysis.
+
+This package contains various analysis modules for static analysis of Python
+code, including control flow analysis, data flow analysis, inter-procedural
+analysis, constraint-based analysis, and shape analysis.
+"""
+
+# Import main analysis modules
+from . import shape
+from . import ipa
+from . import cpa
+from . import fsdf
+from . import alias
+from . import ifds
+from . import taint_policy

pyflow_analysis-0.1.2/src/pyflow/analysis/alias/flow_sensitive/__init__.py

@@ -0,0 +1,171 @@
+"""Heap abstraction model for static analysis.
+
+The heap model provides canonical :class:`HeapLocation` objects,
+:class:`HeapAbstraction` for alias tracking and strong/weak update policy,
+and factory classes for translating Python IR operations into heap effects.
+
+Submodules
+----------
+* :mod:`.model` — Data model: enums, HeapPolicy, HeapObject, HeapLocation, HeapSelector, HeapWrite
+* :mod:`.abstraction` — HeapAbstraction engine: canonicalization, alias tracking, update policies
+* :mod:`.heap_effects` — Translates IR operations into HeapEffect records
+* :mod:`.heap_state` — Flow-sensitive, path-insensitive value state
+* :mod:`.heap_summary` — Procedure-level heap summaries
+* :mod:`.points_to_graph` — Read-only PointsToGraph snapshot for optimization passes
+* :mod:`.heap_analysis` — Standalone HeapAnalysis engine and pass integration
+* :mod:`.intrinsics` — Heap-owned built-in call and collection models
+* :mod:`.transfer` — Standalone forward transfer engine
+
+Examples
+--------
+
+>>> from pyflow.analysis.alias.flow_sensitive import HeapPolicy, HeapAbstraction, HeapEffect
+
+>>> policy = HeapPolicy.context_sensitive(depth=2)
+>>> policy.validate()  # catch misconfigurations early
+
+>>> effect = HeapEffect(reads=(...), writes=(...))
+>>> bool(effect)
+True
+>>> effect.is_empty
+False
+>>> merged = effect.merge(other_effect)
+
+>>> heap = HeapAbstraction(raw_storage_provider, policy=policy)
+>>> heap.to_dict()
+{'policy': {...}, 'next_site': 0, 'cached_objects': 0, ...}
+
+Standalone ``HeapAnalysis`` performs a flow-sensitive, path-insensitive
+forward sweep over discoverable code objects.  It keeps precise field and
+literal-key values when possible and records wildcard writes as contaminating
+overlapping paths instead of flattening unrelated exact facts.
+"""
+
+from .model import (
+    AllocationSensitivity,
+    ContainerSensitivity,
+    FieldSensitivity,
+    HeapEscapeState,
+    HeapLocation,
+    HeapObject,
+    HeapObjectCardinality,
+    HeapObjectIdentity,
+    HeapObjectFreshness,
+    HeapObjectKind,
+    HeapPolicy,
+    HeapSelector,
+    HeapWrite,
+    RawStorageProvider,
+    UpdatePolicy,
+)
+
+from .domain.abstraction import (
+    HeapAbstraction,
+    HeapEnvironment,
+)
+
+from .semantics.effects import (
+    CALL_RETURN_COPY,
+    CALL_RETURN_FRESH,
+    CALL_RETURN_OPAQUE,
+    CALL_RETURN_SUMMARY,
+    COLLECTION_DELETE_MUTATOR_NAMES,
+    COLLECTION_VALUE_MUTATOR_NAMES,
+    DEFAULT_COLLECTION_MUTATOR_NAMES,
+    HeapEffect,
+    HeapEffectBuilder,
+    HeapOperationSemantics,
+)
+
+from .semantics.intrinsics import (
+    CollectionMutatorModel,
+    DEFAULT_HEAP_INTRINSICS,
+    HeapIntrinsicModels,
+)
+
+from .domain.state import HeapState
+
+from .domain.summary import (
+    HeapSummary,
+    HeapSummaryBuilder,
+    ProcedureHeapSummary,
+)
+
+from .domain.points_to import (
+    HeapValueSnapshot,
+    PossibleValues,
+    PointsToEntry,
+    PointsToGraph,
+)
+
+from .heap_analysis import (
+    HeapAnalysis,
+)
+
+from .transfer import HeapTransferEngine
+
+# Preserve the historical module paths while keeping implementation files in
+# responsibility-focused subpackages.
+import sys as _sys
+
+from .domain import abstraction as _abstraction_module
+from .domain import points_to as _points_to_module
+from .domain import state as _state_module
+from .domain import summary as _summary_module
+from .semantics import effects as _effects_module
+from .semantics import intrinsics as _intrinsics_module
+
+_LEGACY_MODULES = {
+    "abstraction": _abstraction_module,
+    "heap_effects": _effects_module,
+    "heap_state": _state_module,
+    "heap_summary": _summary_module,
+    "intrinsics": _intrinsics_module,
+    "points_to_graph": _points_to_module,
+}
+for _legacy_name, _legacy_module in _LEGACY_MODULES.items():
+    _sys.modules[f"{__name__}.{_legacy_name}"] = _legacy_module
+    globals()[_legacy_name] = _legacy_module
+
+__all__ = [
+    "AllocationSensitivity",
+    "CALL_RETURN_COPY",
+    "CALL_RETURN_FRESH",
+    "CALL_RETURN_OPAQUE",
+    "CALL_RETURN_SUMMARY",
+    "COLLECTION_DELETE_MUTATOR_NAMES",
+    "COLLECTION_VALUE_MUTATOR_NAMES",
+    "CollectionMutatorModel",
+    "ContainerSensitivity",
+    "DEFAULT_COLLECTION_MUTATOR_NAMES",
+    "DEFAULT_HEAP_INTRINSICS",
+    "FieldSensitivity",
+    "HeapAbstraction",
+    "HeapAnalysis",
+    "HeapEffect",
+    "HeapEffectBuilder",
+    "HeapOperationSemantics",
+    "HeapEnvironment",
+    "HeapEscapeState",
+    "HeapLocation",
+    "HeapObject",
+    "HeapObjectCardinality",
+    "HeapObjectIdentity",
+    "HeapObjectFreshness",
+    "HeapObjectKind",
+    "HeapPolicy",
+    "HeapSelector",
+    "HeapState",
+    "HeapSummary",
+    "HeapTransferEngine",
+    "HeapIntrinsicModels",
+    "HeapSummaryBuilder",
+    "ProcedureHeapSummary",
+    "HeapWrite",
+    "HeapValueSnapshot",
+    "PointsToEntry",
+    "PointsToGraph",
+    "PossibleValues",
+    "RawStorageProvider",
+    "UpdatePolicy",
+]

pyflow_analysis-0.1.2/src/pyflow/analysis/alias/flow_sensitive/domain/__init__.py

@@ -0,0 +1 @@
+"""Heap abstraction state, summaries, and query snapshots."""