porifera 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,158 @@
1
+ Metadata-Version: 2.3
2
+ Name: porifera
3
+ Version: 0.1.0
4
+ Summary: PORIFERA: PHP code rewriting instrumentation for expression in AST
5
+ Requires-Dist: php-parser-py>=1.2.2
6
+ Requires-Python: >=3.11, <3.13
7
+ Description-Content-Type: text/markdown
8
+
9
+ # PORIFERA: Php cOde Rewriting Instrumentation For ExpRession in Ast
10
+
11
+ > Porifera (Sponges) are the oldest porous filter-feeding organisms in the ocean. Sponges draw in seawater through micro-pores throughout their bodies, filter it, and capture nutrients.
12
+ > PORIFERA uses this as a metaphor: Like the pores of a sponge, it permeates each expression in the code, silently absorbing runtime values without altering the behavior of the program itself.
13
+
14
+ PHP AST instrumentation library. Injects runtime probe wrappers around target PHP expressions to capture their values, then restores the original code.
15
+
16
+ Requires Python >=3.11,<3.13.
17
+
18
+ ## Installation
19
+
20
+ ```bash
21
+ pip install porifera
22
+ ```
23
+
24
+ ## Quick Start
25
+
26
+ ```python
27
+ from php_parser_py import Parser
28
+ from porifera import instrument, deinstrument
29
+
30
+ # Parse PHP project
31
+ ast = Parser().parse_file("path/to/project/index.php")
32
+
33
+ # Define targets: AST node_id -> expr_key label
34
+ targets = {
35
+ "node_42": "user_query",
36
+ "node_87": "config_value",
37
+ }
38
+
39
+ # Instrument — wraps targets with probe calls
40
+ modified_files = instrument(targets, ast)
41
+
42
+ # Optionally specify output directory for probe logs
43
+ # modified_files = instrument(targets, ast, output_dir=Path("/tmp/logs"))
44
+
45
+ # Run PHP project... probes log to .porifera_data_<timestamp>.jsonl
46
+
47
+ # Deinstrument — restores original code
48
+ restored_files = deinstrument(ast)
49
+ ```
50
+
51
+ After instrumentation, a PHP expression like:
52
+
53
+ ```php
54
+ $row = $db->query($sql);
55
+ ```
56
+
57
+ becomes:
58
+
59
+ ```php
60
+ $row = __porifera_probe_a1b2c3d4("user_query", $db->query($sql));
61
+ ```
62
+
63
+ The probe returns the original value transparently and logs it to `.porifera_data_<timestamp>.jsonl`. Each instrumentation run produces a unique timestamped file to avoid overwriting previous data.
64
+
65
+ ## Examples
66
+
67
+ ### Log all array access values at runtime
68
+
69
+ Probe every `$config['db_host']`, `$row['name']`, etc.:
70
+
71
+ ```python
72
+ from php_parser_py import Parser
73
+ from porifera import instrument
74
+
75
+ ast = Parser().parse_file("app/config.php")
76
+
77
+ # All Expr_ArrayDimFetch nodes -> targets
78
+ fetches = ast.nodes(lambda n: n.node_type == "Expr_ArrayDimFetch")
79
+ targets = {n.id: f"array_{n.id[:8]}" for n in fetches}
80
+
81
+ instrument(targets, ast)
82
+ ```
83
+
84
+ ### Log all function call return values
85
+
86
+ Probe every function call:
87
+
88
+ ```python
89
+ from php_parser_py import Parser
90
+ from porifera import instrument
91
+
92
+ ast = Parser().parse_file("app/service.php")
93
+
94
+ # All Expr_FuncCall nodes -> targets
95
+ calls = ast.nodes(lambda n: n.node_type == "Expr_FuncCall")
96
+ targets = {n.id: f"call_{n.id[:8]}" for n in calls}
97
+
98
+ instrument(targets, ast)
99
+ ```
100
+
101
+ ### Log specific function call return values
102
+
103
+ Probe only `mysqli_query(...)` calls:
104
+
105
+ ```python
106
+ from php_parser_py import Parser
107
+ from porifera import instrument
108
+
109
+ ast = Parser().parse_file("app/db.php")
110
+
111
+ # All Expr_FuncCall nodes
112
+ calls = ast.nodes(lambda n: n.node_type == "Expr_FuncCall")
113
+
114
+ # Filter by function name
115
+ targets = {}
116
+ for call in calls:
117
+ name_node = next(ast.succ(call, lambda e: e.get("field") == "name"), None)
118
+ if not name_node or name_node.get_property("parts") != ["mysqli_query"]: continue
119
+ targets[call.id] = f"query_{call.id[:8]}"
120
+
121
+ instrument(targets, ast)
122
+ ```
123
+
124
+ ### Broader coverage with ElevatingProbeStrategy
125
+
126
+ `StandardProbeStrategy` skips lvalue targets (e.g. `$i` in `$i++`). `ElevatingProbeStrategy` wraps the nearest safe ancestor instead:
127
+
128
+ ```python
129
+ from porifera import instrument, ElevatingProbeStrategy
130
+
131
+ instrument(targets, ast, strategy=ElevatingProbeStrategy())
132
+ ```
133
+
134
+ ## Documentation
135
+
136
+ - [Design Specification](docs/design.md) — API signatures, class responsibilities, strategies, exceptions, and validation rules
137
+ - [Implementation Notes](docs/impl.md) — php-parser-py API reference, AST node types, unsafe wrap contexts, and developer instructions
138
+ - [AST Structure](https://github.com/jhu-seclab-beluga/php-parser-py/blob/main/docs/libs/php_parser_ast.md) - the structure of the php-parser-py AST, node types, and properties, and how to navigate it.
139
+
140
+ ## Development
141
+
142
+ ```bash
143
+ # Install dependencies
144
+ uv sync
145
+
146
+ # Run tests
147
+ uv run pytest
148
+
149
+ # Type checking
150
+ uv run mypy src/
151
+
152
+ # Linting
153
+ uv run pylint src/
154
+
155
+ # Formatting
156
+ uv run black src/ tests/
157
+ uv run isort src/ tests/
158
+ ```
@@ -0,0 +1,150 @@
1
+ # PORIFERA: Php cOde Rewriting Instrumentation For ExpRession in Ast
2
+
3
+ > Porifera (Sponges) are the oldest porous filter-feeding organisms in the ocean. Sponges draw in seawater through micro-pores throughout their bodies, filter it, and capture nutrients.
4
+ > PORIFERA uses this as a metaphor: Like the pores of a sponge, it permeates each expression in the code, silently absorbing runtime values without altering the behavior of the program itself.
5
+
6
+ PHP AST instrumentation library. Injects runtime probe wrappers around target PHP expressions to capture their values, then restores the original code.
7
+
8
+ Requires Python >=3.11,<3.13.
9
+
10
+ ## Installation
11
+
12
+ ```bash
13
+ pip install porifera
14
+ ```
15
+
16
+ ## Quick Start
17
+
18
+ ```python
19
+ from php_parser_py import Parser
20
+ from porifera import instrument, deinstrument
21
+
22
+ # Parse PHP project
23
+ ast = Parser().parse_file("path/to/project/index.php")
24
+
25
+ # Define targets: AST node_id -> expr_key label
26
+ targets = {
27
+ "node_42": "user_query",
28
+ "node_87": "config_value",
29
+ }
30
+
31
+ # Instrument — wraps targets with probe calls
32
+ modified_files = instrument(targets, ast)
33
+
34
+ # Optionally specify output directory for probe logs
35
+ # modified_files = instrument(targets, ast, output_dir=Path("/tmp/logs"))
36
+
37
+ # Run PHP project... probes log to .porifera_data_<timestamp>.jsonl
38
+
39
+ # Deinstrument — restores original code
40
+ restored_files = deinstrument(ast)
41
+ ```
42
+
43
+ After instrumentation, a PHP expression like:
44
+
45
+ ```php
46
+ $row = $db->query($sql);
47
+ ```
48
+
49
+ becomes:
50
+
51
+ ```php
52
+ $row = __porifera_probe_a1b2c3d4("user_query", $db->query($sql));
53
+ ```
54
+
55
+ The probe returns the original value transparently and logs it to `.porifera_data_<timestamp>.jsonl`. Each instrumentation run produces a unique timestamped file to avoid overwriting previous data.
56
+
57
+ ## Examples
58
+
59
+ ### Log all array access values at runtime
60
+
61
+ Probe every `$config['db_host']`, `$row['name']`, etc.:
62
+
63
+ ```python
64
+ from php_parser_py import Parser
65
+ from porifera import instrument
66
+
67
+ ast = Parser().parse_file("app/config.php")
68
+
69
+ # All Expr_ArrayDimFetch nodes -> targets
70
+ fetches = ast.nodes(lambda n: n.node_type == "Expr_ArrayDimFetch")
71
+ targets = {n.id: f"array_{n.id[:8]}" for n in fetches}
72
+
73
+ instrument(targets, ast)
74
+ ```
75
+
76
+ ### Log all function call return values
77
+
78
+ Probe every function call:
79
+
80
+ ```python
81
+ from php_parser_py import Parser
82
+ from porifera import instrument
83
+
84
+ ast = Parser().parse_file("app/service.php")
85
+
86
+ # All Expr_FuncCall nodes -> targets
87
+ calls = ast.nodes(lambda n: n.node_type == "Expr_FuncCall")
88
+ targets = {n.id: f"call_{n.id[:8]}" for n in calls}
89
+
90
+ instrument(targets, ast)
91
+ ```
92
+
93
+ ### Log specific function call return values
94
+
95
+ Probe only `mysqli_query(...)` calls:
96
+
97
+ ```python
98
+ from php_parser_py import Parser
99
+ from porifera import instrument
100
+
101
+ ast = Parser().parse_file("app/db.php")
102
+
103
+ # All Expr_FuncCall nodes
104
+ calls = ast.nodes(lambda n: n.node_type == "Expr_FuncCall")
105
+
106
+ # Filter by function name
107
+ targets = {}
108
+ for call in calls:
109
+ name_node = next(ast.succ(call, lambda e: e.get("field") == "name"), None)
110
+ if not name_node or name_node.get_property("parts") != ["mysqli_query"]: continue
111
+ targets[call.id] = f"query_{call.id[:8]}"
112
+
113
+ instrument(targets, ast)
114
+ ```
115
+
116
+ ### Broader coverage with ElevatingProbeStrategy
117
+
118
+ `StandardProbeStrategy` skips lvalue targets (e.g. `$i` in `$i++`). `ElevatingProbeStrategy` wraps the nearest safe ancestor instead:
119
+
120
+ ```python
121
+ from porifera import instrument, ElevatingProbeStrategy
122
+
123
+ instrument(targets, ast, strategy=ElevatingProbeStrategy())
124
+ ```
125
+
126
+ ## Documentation
127
+
128
+ - [Design Specification](docs/design.md) — API signatures, class responsibilities, strategies, exceptions, and validation rules
129
+ - [Implementation Notes](docs/impl.md) — php-parser-py API reference, AST node types, unsafe wrap contexts, and developer instructions
130
+ - [AST Structure](https://github.com/jhu-seclab-beluga/php-parser-py/blob/main/docs/libs/php_parser_ast.md) - the structure of the php-parser-py AST, node types, and properties, and how to navigate it.
131
+
132
+ ## Development
133
+
134
+ ```bash
135
+ # Install dependencies
136
+ uv sync
137
+
138
+ # Run tests
139
+ uv run pytest
140
+
141
+ # Type checking
142
+ uv run mypy src/
143
+
144
+ # Linting
145
+ uv run pylint src/
146
+
147
+ # Formatting
148
+ uv run black src/ tests/
149
+ uv run isort src/ tests/
150
+ ```
@@ -0,0 +1,40 @@
1
+ [project]
2
+ name = "porifera"
3
+ version = "0.1.0"
4
+ description = "PORIFERA: PHP code rewriting instrumentation for expression in AST"
5
+ readme = "README.md"
6
+ requires-python = ">=3.11,<3.13"
7
+ dependencies = [
8
+ "php-parser-py>=1.2.2",
9
+ ]
10
+
11
+ [dependency-groups]
12
+ dev = [
13
+ "pytest>=8.0",
14
+ "pytest-cov>=5.0",
15
+ "mypy>=1.11",
16
+ "pylint>=3.2",
17
+ "black>=24.4",
18
+ "isort>=5.13",
19
+ ]
20
+
21
+ [build-system]
22
+ requires = ["uv_build>=0.10.4,<0.11.0"]
23
+ build-backend = "uv_build"
24
+
25
+ [tool.pytest.ini_options]
26
+ testpaths = ["tests"]
27
+ pythonpath = ["tests"]
28
+ python_files = ["test_*.py"]
29
+ addopts = ["-v", "--tb=short", "--strict-markers"]
30
+
31
+ [tool.isort]
32
+ profile = "black"
33
+
34
+ [[tool.mypy.overrides]]
35
+ module = "php_parser_py.*"
36
+ ignore_missing_imports = true
37
+
38
+ [tool.uv]
39
+ # uv will recognize this project via pyproject.toml; keep this table for
40
+ # project-specific uv settings in future if needed.
Binary file
@@ -0,0 +1,18 @@
1
+ """PORIFERA: PHP AST instrumentation module.
2
+
3
+ Exports public API functions and strategy classes for PHP AST instrumentation.
4
+ """
5
+
6
+ from ._exceptions import DeinstrumentationError, InstrumentationError
7
+ from ._manager import deinstrument, instrument
8
+ from ._strategies import ElevatingProbeStrategy, ProbeStrategy, StandardProbeStrategy
9
+
10
+ __all__ = [
11
+ "instrument",
12
+ "deinstrument",
13
+ "InstrumentationError",
14
+ "DeinstrumentationError",
15
+ "ProbeStrategy",
16
+ "StandardProbeStrategy",
17
+ "ElevatingProbeStrategy",
18
+ ]
@@ -0,0 +1,13 @@
1
+ """Exceptions for instrumentation operations."""
2
+
3
+
4
+ class InstrumentationError(Exception):
5
+ """Raised during instrumentation (parse error, write failure, registry error)."""
6
+
7
+ def __init__(self, message: str) -> None:
8
+ super().__init__(message)
9
+ self.message = message
10
+
11
+
12
+ class DeinstrumentationError(InstrumentationError):
13
+ """Raised during deinstrumentation (registry corrupted, AST parse error)."""