Skip to content

Commit ed72b4b

Browse files
EdgeTypEEdgeTypE
committed
hi
1 parent 99d1798 commit ed72b4b

48 files changed

Lines changed: 6209 additions & 1 deletion

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: CI
2+
on:
3+
push:
4+
branches: [ main ]
5+
pull_request:
6+
branches: [ main ]
7+
jobs:
8+
test:
9+
runs-on: ubuntu-latest
10+
strategy:
11+
matrix:
12+
python-version: [3.10, 3.11, 3.12]
13+
extras: [none, fast]
14+
steps:
15+
- name: Check out repository
16+
uses: actions/checkout@v4
17+
18+
- name: Set up Python ${{ matrix.python-version }}
19+
uses: actions/setup-python@v4
20+
with:
21+
python-version: ${{ matrix.python-version }}
22+
23+
- name: Cache pip
24+
uses: actions/cache@v4
25+
with:
26+
path: ~/.cache/pip
27+
key: ${{ runner.os }}-pip-${{ matrix.python-version }}-${{ matrix.extras }}
28+
29+
- name: Install dependencies
30+
run: |
31+
python -m pip install --upgrade pip
32+
if [ "${{ matrix.extras }}" = "fast" ]; then
33+
pip install .[test,fast]
34+
else
35+
pip install .[test]
36+
fi
37+
pip install ruff mypy black coverage
38+
39+
- name: Run linters and type checks
40+
run: |
41+
ruff check .
42+
black --check .
43+
mypy patternlab || true
44+
45+
- name: Run tests with coverage
46+
run: |
47+
coverage run -m pytest
48+
coverage xml -i
49+
coverage report -m
50+
51+
- name: Upload coverage report
52+
uses: actions/upload-artifact@v4
53+
with:
54+
name: coverage-${{ matrix.python-version }}-${{ matrix.extras }}
55+
path: coverage.xml

‎README.md‎

Lines changed: 199 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,200 @@
1-
# pattern-analyzer
1+
# PatternLab
22

3+
Binary pattern analysis framework for statistical testing and transformation of binary data.
4+
5+
## Features
6+
7+
- **Plugin Architecture**: Extensible system for transforms and statistical tests
8+
- **XOR Transform**: Apply constant XOR transformation to binary data
9+
- **Monobit Test**: Statistical frequency test for binary sequences
10+
- **CLI Interface**: Command-line tool for easy analysis
11+
- **Python API**: Programmatic access to all functionality
12+
13+
## Installation
14+
15+
### From Source
16+
17+
```bash
18+
# Clone the repository
19+
git clone <repository-url>
20+
cd patternlab
21+
22+
# Install in development mode
23+
pip install -e .
24+
```
25+
26+
### Dependencies
27+
28+
- Python 3.10+
29+
- click (for CLI)
30+
- pytest (for testing)
31+
32+
## Usage
33+
34+
### Command Line Interface
35+
36+
Analyze a binary file:
37+
38+
```bash
39+
# Basic analysis (writes JSON with top-level keys "results" and "scorecard")
40+
patternlab analyze input.bin --out results.json
41+
42+
# With XOR constant transformation
43+
patternlab analyze input.bin --out results.json --xor-value 255
44+
```
45+
46+
Options:
47+
- `input-file`: Path to binary file to analyze
48+
- `--out`: Output JSON file (default: report.json)
49+
- `--xor-value`: XOR value for transformation (0-255, default: 0)
50+
51+
CLI example — updated JSON output (file written to `results.json`; top-level schema shown below):
52+
53+
Top-level schema:
54+
55+
```json
56+
{
57+
"results": [...],
58+
"scorecard": {...}
59+
}
60+
```
61+
62+
Full example output (file written to `results.json`):
63+
64+
```json
65+
{
66+
"results": [
67+
{
68+
"test_name": "monobit",
69+
"passed": true,
70+
"p_value": 0.05,
71+
"p_values": {"overall": 0.05},
72+
"effect_sizes": {"overall": 0.8},
73+
"flags": [],
74+
"metrics": {"bit_count": 1000},
75+
"z_score": 1.96,
76+
"evidence": null,
77+
"fdr_rejected": false,
78+
"fdr_q": 0.05
79+
}
80+
],
81+
"scorecard": {
82+
"failed_tests": 0,
83+
"mean_effect_size": 0.8,
84+
"p_value_distribution": {
85+
"count": 1,
86+
"mean": 0.05,
87+
"median": 0.05,
88+
"stdev": 0.0,
89+
"histogram": {"0-0.01": 0, "0.01-0.05": 0, "0.05-0.1": 1, "0.1-1.0": 0}
90+
},
91+
"total_tests": 1,
92+
"fdr_q": 0.05
93+
}
94+
}
95+
```
96+
97+
### Python API
98+
99+
```python
100+
from patternlab.engine import Engine
101+
from patternlab.plugins.xor_const import XOPlugin
102+
from patternlab.plugins.monobit import MonobitTest
103+
from patternlab.plugin_api import BytesView, serialize_testresult
104+
import json
105+
106+
# Engine ve plugin kayıtları
107+
engine = Engine()
108+
engine.register_transform('xor_const', XOPlugin())
109+
engine.register_test('monobit', MonobitTest())
110+
111+
# Veri analizi
112+
with open('input.bin', 'rb') as f:
113+
data = f.read()
114+
115+
config = {'transforms': [{'name': 'xor_const', 'params': {'xor_value': 255}}], 'tests': [{'name': 'monobit', 'params': {}}]}
116+
output = engine.analyze(data, config)
117+
118+
# `engine.analyze` fonksiyonu top-level bir dict döner:
119+
# { "results": [...], "scorecard": {...} }
120+
# TestResult'ları canonical JSON şemasına çevirmek için serialize_testresult kullanılmaktadır.
121+
print(json.dumps(output, indent=2))
122+
```
123+
124+
Örnek serializasyon (yeni TestResult şeması — CLI ve engine tarafından üretilen her bir sonuç bu şemaya uyar):
125+
```json
126+
{
127+
"test_name": "monobit",
128+
"passed": true,
129+
"p_value": 0.05,
130+
"p_values": {"overall": 0.05},
131+
"effect_sizes": {"overall": 0.8},
132+
"flags": ["flag1", "flag2"],
133+
"metrics": {"metric1": 123, "metric2": 456},
134+
"z_score": 1.96,
135+
"evidence": "Some evidence string",
136+
"fdr_rejected": false,
137+
"fdr_q": 0.05
138+
}
139+
```
140+
141+
Not: Eğer eski `details` alanı varsa, `serialize_testresult` fonksiyonu onu `metrics` içine birleştirir.
142+
143+
## Available Plugins
144+
145+
### Transform Plugins
146+
147+
- **xor_const**: Applies XOR transformation with constant value
148+
149+
### Test Plugins
150+
151+
- **monobit**: Monobit frequency test for random number generators
152+
153+
## Testing
154+
155+
Run the test suite:
156+
157+
```bash
158+
# Run all tests
159+
pytest
160+
161+
# Run with verbose output
162+
pytest -v
163+
164+
# Run specific test file
165+
pytest tests/test_xor.py
166+
```
167+
168+
## Project Structure
169+
170+
```
171+
patternlab/
172+
├── __init__.py # Package initialization
173+
├── plugin_api.py # Plugin base classes and data structures
174+
├── engine.py # Main analysis engine
175+
├── cli.py # Command line interface
176+
└── plugins/
177+
├── __init__.py
178+
├── xor_const.py # XOR transform plugin
179+
└── monobit.py # Monobit test plugin
180+
tests/
181+
├── test_xor.py
182+
└── test_monobit.py
183+
```
184+
185+
## License
186+
187+
MIT License - see LICENSE file for details.
188+
189+
## Contributing
190+
191+
1. Fork the repository
192+
2. Create a feature branch
193+
3. Add tests for new functionality
194+
4. Ensure all tests pass: `pytest`
195+
5. Submit a pull request
196+
197+
## Requirements
198+
199+
- Python 3.10 or higher
200+
- No external dependencies beyond standard library (except for development)

‎docs/configs/README.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Config Örnekleri
2+
3+
Bu dizin, PatternLab için JSON ve YAML formatında örnek konfigürasyon dosyaları içerir.
4+
5+
Dosyalar:
6+
- [`docs/configs/example.json`](docs/configs/example.json:1) — JSON örneği
7+
- [`docs/configs/example.yml`](docs/configs/example.yml:1) — YAML örneği
8+
9+
Açıklama (alanlar):
10+
- transforms: Sıralı dönüşümler. Her öğe string veya {"name": .., "params": {...}} olabilir.
11+
- tests: Çalıştırılacak testler listesi. Her öğe string veya {"name": .., "params": {...}} olabilir.
12+
- fdr_q: FDR düzeltmesi için q (ör. 0.05).
13+
- visuals: Görsel eklentiler için parametre haritası (örn. {"fft_placeholder": {"mime": "image/svg+xml"}}).
14+
- html_report: Engine tarafından yazılacak minimal HTML raporun yolu.
15+
- log_path: JSONL formatında test log satırlarının yazılacağı dosya yolu.
16+
17+
Kullanım - CLI:
18+
19+
patternlab analyze ./test.bin -c docs/configs/example.json -o report.json
20+
21+
Kullanım - Programatik:
22+
23+
from patternlab.engine import Engine
24+
engine = Engine()
25+
with open("test.bin","rb") as f:
26+
out = engine.analyze(f.read(), config)
27+
28+
Notlar:
29+
- YAML dosyaları yüklemek için PyYAML gerekli olabilir.
30+
- Config içindeki test girdi formatları CLI tarafından normalize edilir (bakınız [`patternlab/cli.py`](patternlab/cli.py:1)).
31+
- Daha fazla örnek gerektiğinde bu dizine yeni dosyalar ekleyin.

‎docs/configs/example.json‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
{
2+
"transforms": [
3+
{
4+
"name": "xor_const",
5+
"params": { "xor_value": 55 }
6+
}
7+
],
8+
"tests": [
9+
{
10+
"name": "monobit",
11+
"params": { "alpha": 0.01 }
12+
},
13+
{
14+
"name": "runs",
15+
"params": { "min_bits": 20, "alpha": 0.01 }
16+
},
17+
{
18+
"name": "block_frequency",
19+
"params": { "block_size": 8, "alpha": 0.01 }
20+
},
21+
{
22+
"name": "serial",
23+
"params": { "max_m": 4, "alpha": 0.01 }
24+
},
25+
{
26+
"name": "fft_spectral",
27+
"params": {}
28+
}
29+
],
30+
"fdr_q": 0.05,
31+
"visuals": { "fft_placeholder": { "mime": "image/svg+xml", "width": 600, "height": 160 } },
32+
"html_report": "reports/report.html",
33+
"log_path": "reports/tests.log"
34+
}

‎docs/configs/example.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
transforms:
2+
- name: xor_const
3+
params:
4+
xor_value: 55
5+
6+
tests:
7+
- name: monobit
8+
params:
9+
alpha: 0.01
10+
- name: runs
11+
params:
12+
min_bits: 20
13+
alpha: 0.01
14+
- name: block_frequency
15+
params:
16+
block_size: 8
17+
alpha: 0.01
18+
- name: serial
19+
params:
20+
max_m: 4
21+
alpha: 0.01
22+
- name: fft_spectral
23+
params: {}
24+
25+
fdr_q: 0.05
26+
visuals:
27+
fft_placeholder:
28+
mime: "image/svg+xml"
29+
width: 600
30+
height: 160
31+
html_report: "reports/report.html"
32+
log_path: "reports/tests.log"

0 commit comments

Comments
 (0)