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.
- porifera-0.1.0/PKG-INFO +158 -0
- porifera-0.1.0/README.md +150 -0
- porifera-0.1.0/pyproject.toml +40 -0
- porifera-0.1.0/src/porifera/.DS_Store +0 -0
- porifera-0.1.0/src/porifera/__init__.py +18 -0
- porifera-0.1.0/src/porifera/_exceptions.py +13 -0
- porifera-0.1.0/src/porifera/_manager.py +345 -0
- porifera-0.1.0/src/porifera/_operations/__init__.py +14 -0
- porifera-0.1.0/src/porifera/_operations/_deinstrumenter.py +234 -0
- porifera-0.1.0/src/porifera/_operations/_instrumenter.py +158 -0
- porifera-0.1.0/src/porifera/_registry.py +74 -0
- porifera-0.1.0/src/porifera/_strategies/__init__.py +18 -0
- porifera-0.1.0/src/porifera/_strategies/_base.py +83 -0
- porifera-0.1.0/src/porifera/_strategies/_elevating.py +49 -0
- porifera-0.1.0/src/porifera/_strategies/_standard.py +25 -0
- porifera-0.1.0/src/porifera/py.typed +0 -0
- porifera-0.1.0/src/porifera/resources/__init__.py +0 -0
- porifera-0.1.0/src/porifera/resources/porifera_runtime.php +14 -0
porifera-0.1.0/PKG-INFO
ADDED
|
@@ -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
|
+
```
|
porifera-0.1.0/README.md
ADDED
|
@@ -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)."""
|