PYAS: a layered Windows endpoint security project you can read

Ten detection layers, and the table that says which API does what

PYAS is described as a hybrid Windows endpoint security platform powered by machine learning, YARA rules, cloud analysis and kernel-level behavioral protection, and the protection capabilities are laid out as a table of layer, capability and implementation.

Static rules handle file and process-memory matching, with YARA rules compiled and loaded by `rule_scanner`. PE machine learning does feature extraction and local classification using `pefile`, NumPy and ONNX Runtime. Signature trust is Authenticode verification through the Windows WinVerifyTrust APIs. Cloud integration is optional file submission and online analysis, through a desktop HTTPS client talking to an externally hosted service.

Then the behavioural half. Process protection covers new-process inspection with optional suspension and termination controls, built on Win32 and NT APIs and worker pools. File protection does directory change monitoring, debounced real-time scans and file locking through the Windows file notification APIs. Memory protection is process-memory YARA scanning plus kernel callbacks, from a user-mode scanner plus driver rules. Network visibility is process-aware TCP connection monitoring using the Windows IP Helper APIs. Kernel enforcement covers file, process and thread, registry, memory, image-load and boot or disk controls through the native C++ minifilter driver. And recovery and maintenance is quarantine, system repair, startup management, cleanup and MBR backup and check, in the Python application services.

What that list makes clear is the spread. The first four layers are about a file you are handed, the next four are about what happens while the system runs, and the last is about the operational consequence of all of it. Each layer is individually configurable, and the README says to review the available controls and enable those appropriate for your environment, which is the instruction you would want given that the same list includes registry controls and boot controls.

The project positions itself as both a usable application and an engineering platform for studying malware detection, Windows internals, rule-driven prevention, model training and online file analysis, and the repository layout supports the second half of that claim, with a models and training utilities directory and a visual rule editor named in the feature list.

The architecture splits the interface from the engines and the driver

The system architecture section separates four concerns, and the diagram in the README shows how they connect.

The desktop application separates presentation, application services, detection engines and Windows integration. Shared modules handle configuration, logging, storage and scheduling. The presentation layer is a WebView2 interface and a system tray, which sits above `PYAS.py` as the application, and the application in turn drives scanning services, protection services and maintenance and system tools.

Both the scanning path and the protection path point at the same detection engines, and the engines fan out to three sources: YARA rules, PE features and ONNX models, and signature verification. The protection services talk to the Windows filter driver, and the tools path uses shared Windows APIs. The cloud client is drawn with a dashed optional edge from the scanning services, and the external cloud service is reached over HTTPS from there.

Two details in that diagram matter more than they look.

The first is that scanning and protection converge on one set of engines. A rule that is used to detect a file during a scan is the same rule that the real-time monitor evaluates when a process starts or a file changes. That is the difference between a scanner and an endpoint product, and it is why the project describes itself as protection rather than scanning.

The second is the boundary of the public source. The public source contains the desktop cloud client, and the cloud server implementation and deployment code are not included in the public repository. So the client side of the optional submission feature is open and the service side is not, which is a reasonable arrangement but one you have to plan for: you can run the whole product locally with cloud submission off, and you cannot run the hosted analysis service from this tree.

The README also carries an explicit warning: PYAS is an independent security project, no antivirus product can guarantee detection of every threat, and you should evaluate it in a controlled environment before production use, keep backups and review alerts before deleting files.

A flat tree of PYAS modules, which is both a strength and a limit

The repository layout is unusually flat and, because the files are named after their comments, unusually readable without opening anything.

PYAS/
├── PYAS.py                  # Desktop entry point and UI bridge
├── PYAS_Startup.py          # Application startup
├── PYAS_Runtime.py          # Runtime state and lifecycle
├── PYAS_Config.py           # Configuration management
├── PYAS_Logs.py             # Activity records and export
├── PYAS_Diagnostics.py      # Exception and diagnostic reporting
├── PYAS_Storage.py          # Shared file storage
├── PYAS_Scheduler.py        # Task scheduling
├── PYAS_WinAPI.py           # Shared Windows APIs
├── PYAS_Scanner.py          # Scan workers, results and remediation
├── PYAS_Engine.py           # Detection engine integration
├── PYAS_Rules.py            # YARA rule scanning
├── PYAS_PE.py               # PE model inference
├── PYAS_Features.py         # PE feature extraction
├── PYAS_Signature.py        # Digital signature verification
├── PYAS_Cloud.py            # Cloud client and submission queue
├── PYAS_Protect.py          # Protection service integration
├── PYAS_Realtime.py         # Real-time monitoring
├── PYAS_Driver.py           # Driver lifecycle and communication
├── PYAS_System.py           # System protection controls
├── PYAS_Popup.py            # Popup selection and blocking
├── PYAS_Tools.py            # Tool service integration
├── PYAS_Autostart.py        # Startup management
├── PYAS_Process.py          # Process and network tools
├── PYAS_Maintenance.py      # Cleanup and repair tools
├── PYAS_Threats.py          # Quarantine and threat management
├── PYAS_Version.py          # Executable version metadata
├── Engine/
│   ├── Heuristic/           # YARA rules and assets
│   └── Properties/          # Models and training utilities
├── Interface/              # HTML, CSS, JavaSc

Read the comments and the structure of the application becomes obvious without any further reading. Configuration, logging, storage and scheduling are shared modules that everything else uses. Scanner, Engine, Rules, PE, Features and Signature are the detection side. Protect, Realtime, Driver, System and Popup are the enforcement side. Cloud is the optional submission path. Tools, Autostart, Process, Maintenance and Threats are the operational surface around it.

The two subdirectories carry the parts that are the project rather than the plumbing. `Engine/Heuristic/` holds the YARA rules and assets, and `Engine/Properties/` holds the models and the training utilities, so the machine learning side is not just an ONNX file you download but a pipeline you can retrain. The `Interface/` directory holds the HTML, CSS and JavaScript for the WebView2 front end.

The top level listing adds two things the tree does not show. `PYAS_Inno.iss` is an Inno Setup script, which is the Windows installer generator, so the project ships as a built installer rather than a script you have to run. And `Plugins/` is where the C++ side lives, since the badge for the C++ kernel points at `Plugins/Filter`, which is where the minifilter driver lives.

The flatness is a real design choice. There is no deep package hierarchy to navigate, and each file has one job, which makes it easy to find the piece you want to read. The cost is that the relationships between those files are expressed in code rather than in the directory structure, so a reader wanting to follow one signal end to end still has to read the Python.

What the project is deliberately not

Two things are worth stating plainly, because both are the kind of thing a reader assumes and should not.

The first is that this is source-available rather than open source in the usual sense, and the licence is one GitHub cannot classify. The README calls it a source-available Windows endpoint security project, and there is a `LICENSE.txt` in the repository root whose terms you need to read before you deploy it anywhere.

The second is the cloud boundary again, and it is worth being blunt about what it means operationally. The public source contains the desktop cloud client, and the cloud server implementation and deployment code are not included. The online analysis page linked from the README is therefore a service you can submit to, not one you can run. If your requirement is that every artefact your endpoint sends stays inside your own perimeter, then cloud submission is a setting you leave off and the local layers are what you have.

The project says the same thing about scope in its own words, in the form of a warning: PYAS is an independent security project, no antivirus product can guarantee detection of every threat, evaluate it in a controlled environment before production use, keep backups, and review alerts before deleting files.

That last instruction is the one that reads like it came from experience rather than from a disclaimer template. The quarantine and MBR backup features in the recovery and maintenance layer are the ones that touch a boot sector, and the project tells you to keep backups while offering a tool that touches boot sectors. That combination is only defensible with backups, and it is why the warning is written the way it is.

The research framing is the other half of the project's identity. The overview says the project is designed both as a usable security application and as an engineering platform for studying malware detection, Windows internals, rule-driven prevention, model training and online file analysis, and the feature list names a research-ready codebase with model training utilities, detection engines and a visual rule editor. That is what makes a repository with a custom licence and a private service side a reasonable thing to publish.

Local first, cloud optional, and the queue that makes that work

One line in the Why PYAS list carries most of the operational weight: local-first scanning, meaning the core static analysis is performed on the endpoint, and cloud submission is separately configurable.

That is a design decision about where the trust boundary sits. An endpoint security product that sends every scanned file to a hosted service is a product with a network dependency in the middle of its main loop, and the failure modes of that dependency are not the failure modes of a detection. Doing the classification locally with an ONNX model and a compiled YARA rule set means a disconnected or isolated machine is still protected, and the submission path becomes something you opt into rather than something that happens to you.

The submission path is a queue rather than a synchronous call, and the module names show how. `PYAS_Cloud.py` is the cloud client and submission queue, and `PYAS_Scanner.py` holds the scan workers, the results and the remediation. So a file that is queued for submission is not blocking a scan, and the local decision does not wait on the network.

The detection engines are shared between the two paths, which is what makes the local-only mode genuinely equivalent rather than a reduced version. `PYAS_Engine.py` is the detection engine integration, `PYAS_Rules.py` is the YARA rule scanning, `PYAS_PE.py` is the PE model inference, `PYAS_Features.py` is the PE feature extraction, and `PYAS_Signature.py` is the digital signature verification. That is the whole detection stack, and nothing in it requires a network.

The machine learning side is the interesting part of the local-first claim, because a model you cannot retrain is a model you will eventually be defending against stale. The `Engine/Properties/` directory is described as holding models and training utilities, and the feature list names model training utilities as part of the research-ready codebase. So the models are treated as something you produce, with the feature extraction in `PYAS_Features.py` producing the input the model consumes, rather than as a black box you download.

The topic tags support the same reading from the dependency side: lightgbm, pefile, yara and cpp, alongside antivirus, scanner, kernel and tools. A gradient boosting model over features extracted from a PE file is a straightforward way to score a sample, and keeping the extraction in your own tree is what lets you retrain it against the threats you actually see.

Editorial conclusion

Adopt PYAS if you want to study or prototype Windows endpoint protection, since every detection layer, the rule editor, the model training utilities and the driver sources are in the public tree. Do not adopt it as a drop-in replacement for a commercial endpoint product, because the cloud service implementation and deployment are not in the repository and the project itself says to evaluate it in a controlled environment first, and check first which protection modules you enable, since the driver, registry and boot controls are available and are the part that needs the most careful review.

Frequently asked questions

Official sources

1. 87owo/PYAS on GitHub
2. Issues
3. Project website
4. README
5. Releases