# FlyPHP

FlyPHP is a self-contained, browser-side PHP semantic analyzer backed by a MaleCNS-derived spiking reservoir. Upload a PHP/text file or paste source and analysis starts locally. Tree-sitter maps semantic events onto annotated sensory neurons, propagates them through MaleCNS connectivity, and presents synchronized source/neural telemetry, a 3D fly, and a trained PHP webshell readout.

The FAST-graph readout distinguishes examples resembling benign PHP from examples resembling PHP webshells. An intermediate **SUSPICIOUS** score shows which of the two classes the model leans toward but still requires manual review; it is not a third trained class. Scores are experimental and must not be treated as a definitive security verdict.
Arbitrary pasted text is accepted for inspection, but a submission with no PHP opening tag is marked for review: the model has not been validated on non-PHP text.

## Deploy

Extract the release ZIP and upload its **contents** to a directory such as `public_html/flyphp/`, then open that directory over HTTPS. The host needs PHP 8.1 or later and must serve the static assets as stored. No npm, Python, Composer, database, daemon, rewrite rules, CDN, or command-line setup is required on the host. The release contains neither the user-supplied infection archive nor `.htaccess`; no URL rewrite configuration is needed.

The `.bin.gz` and `.json.gz` graph files must be served as stored bytes without a `Content-Encoding: gzip` response header; the browser verifies and decompresses them itself. A normal Apache/nginx static-file configuration does this. The pinned parser binaries are delivered by `wasm.php`, which guarantees the required `application/wasm` MIME type even on shared hosts with incomplete static MIME mappings. WebGPU requires HTTPS (or localhost). If WebGPU is unavailable, FAST mode falls back visibly to JavaScript. FULL mode automatically falls back to FAST when it cannot obtain a suitable GPU device.

## Privacy and safety

- Selected source is read with the browser File API or pasted into a local form, then sent only to an in-page Web Worker.
- There is no upload endpoint, form submission, server-side scan, PHP execution, `eval`, `include`, shell call, or source-file write.
- The CSP permits network connections only to the same origin. All runtime dependencies are local.
- The default client-side file limit is 5 MB and can be changed in `config.php`.

## Runtime

1. `web-tree-sitter` and `tree-sitter-php` parse PHP as data in a module worker.
2. `assets/php-events.js` extracts positioned semantic events (calls, variables, assignments, control flow, literals, declarations, access operations, and AST context).
3. `assets/fly-encoder.js` hashes structural/text-shape features deterministically onto 64 annotated, non-zero-sign MaleCNS sensory neurons. It contains no malware-function list and no hand-coded verdict rules.
4. The Neural Canvas-derived LIF runtime processes events sequentially and retains recurrent state.
5. Twenty-four per-event reservoir features, including eight genuine transmitter-annotated spike fractions, are aggregated as mean, peak, and last-event features. A trained, standardized binary logistic readout turns these 72 dimensions into a webshell score. It does not use a hard-coded malware-function list.
6. uPlot, the source viewer, 3D fly, and the anatomical neural canvas share one live cursor. Each event is simulated and then plotted at the selected pace (0.25×–4×, default 4×); Pause suspends the simulation itself. The per-event decision is provisional until the last event produces a final result. On desktop, the analysis panels fit in one viewport with scrolling inside long source/result panels. Afterward a dedicated REPLAY 16× button revisits the computed activity quickly.

## Graph modes

**FAST** is the default and the only mode for which the bundled classifier is trained. Selection `flyphp-fast-v2-neurochem` contains 25,521 real MaleCNS neurons, 2,012,517 directed edges, and 14,167,724 released synapses. It extends the original sensory-first 25,000-neuron selection with dopamine-, serotonin-, and octopamine-annotated cells and named descending motor populations. The graph is induced from verified full connectivity; no nodes or edges are random or synthetic. Input neuron indices remain stable.

**FULL** is experimental and memory-intensive. It is the unchanged Neural Canvas representation of 166,700 MaleCNS entries, 25,582,938 directed edges, and 124,177,617 synapses. Its 28 compressed assets were checked against the SHA-256 values published in the upstream manifest before inclusion. When a trained FAST-only readout is present, requesting FULL selects FAST instead so the app does not claim to validate an out-of-distribution verdict.

## Scientific scope

- **Real:** MaleCNS connectivity, released neuron identities, anatomical and transmitter annotations, and synapse counts.
- **Modeled:** LIF dynamics, fast neurotransmitter signs, simulation timing, and transfer of published parameters to MaleCNS.
- **Engineered:** PHP semantic features, event-to-sensory mapping, FAST graph selection, reservoir feature summary, and UI.
- **Trained:** a small webshell-vs-benign PHP readout on graph-derived activity; a middle band requests review. Dopamine-annotated spikes are measured directly, not invented when the score rises. No receptor-specific dopamine physiology, neurotransmitter release model, or biological malware recognition is claimed.

This is an experimental neural-computing instrument, not a claim that a living fly detects malware and not a replacement for established review, sandboxing, or production security tools.

## Readout training and limits

The bundled v4 readout combines two trained linear readouts algebraically into one 72-feature linear model. The training material included files from [hannousse/Cleaned-PHP-Webshell-dataset](https://github.com/hannousse/Cleaned-PHP-Webshell-dataset), six small infection examples from the user-supplied archive, and 22 constructed benign PHP examples. Samples were analyzed as data only, never executed; no sample source or infection archive is in the release. The older readout used 85 public files and the newer readout used 447 public training files. See `data/model/readout.json` for model metadata.

The equal-weight blend and its 25%–75% **SUSPICIOUS** review band were chosen using 273 additional files from the same public corpus. On that **development set**, the binary 50% threshold got 234/273 correct (85.7%); 177/273 files received a decisive CLEAN or MALICIOUS label, of which 167/177 were correct (94.4%). Because those files were used to choose the blend and band, these numbers are **not independent final validation**. False positives and misses remain possible, especially for ordinary PHP outside this corpus. Scores are not calibrated probabilities or an antivirus guarantee; review suspicious and high-impact files with established tools.

## Reuse and provenance

The neural runtime is adapted from [Xenova/fruit-fly-simulation (Neural Canvas)](https://huggingface.co/spaces/Xenova/fruit-fly-simulation) commit `776d115ee5aa934578a87fd6d260d138084f59c1`. Its CSR conversion, LIF parameters, sparse delayed spike queue, WGSL propagation, checksum/cache loader, worker architecture, and CPU fallback remain recognizable. Standard `GPUDevice` acquisition replaces the upstream package-owned device bridge. The articulated 3D specimen reuses its NeuroMechFly meshes, forward kinematics, gait, and six-channel motor controller, rendered with locally bundled Three.js. The 39 STL files, including 18 Git LFS objects, have been verified against their published SHA-256 digests.

The live fly panel uses Neural Canvas's six-channel rate decoder (walking left/right, turning left/right, reverse, and escape) over named descending populations. Because these sparse named cells are often silent over a short PHP event, a broad left/right readout of actual simulated spike counts drives the displayed gait; it is explicitly an engineered movement metaphor, not a measured biological motor command. A small 3D monitor displays the current source event, spike count, dopamine-annotated count, and current trained score; neuron activity lights a different keycap as the articulated fly moves nearby. The visual keyboard is scenery, not game controls or generated output keys. Camera rotation/zoom changes only the view.

[nftechie/doomfly](https://github.com/nftechie/doomfly) commit `71ecf53d78eaffaf1a57ed7b0ccf5d458abc9f33` informed MaleCNS provenance and modeling terminology. The data originate from [MaleCNS v1.0](https://male-cns.janelia.org/download/) and are credited to FlyEM / HHMI Janelia, University of Cambridge, MRC LMB, and Google Research under CC BY 4.0.

Pinned browser dependencies are recorded in `assets/vendor/VERSIONS.json`:

- web-tree-sitter 0.27.0 (MIT)
- tree-sitter-php 0.24.2 (MIT)
- webgpu-utils 2.1.1 (MIT)
- uPlot 1.6.32 (MIT)
- Three.js 0.180.0 (MIT; both module and core module)

License texts and notices are retained in `assets/vendor/licenses/`. Neural Canvas’s detailed model metadata is preserved in `data/metadata/neural-canvas-model.json`, and MaleCNS source locks are preserved in `data/metadata/malecns-source.lock.json`.

## Browser storage

Verified compressed graph chunks are cached with Cache Storage after first use. The **CLEAR LOCAL NEURAL CACHE** control removes only FlyPHP’s neural caches. Selected PHP source is never stored there.