noctyra 0.1.0__tar.gz

noctyra-0.1.0/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(timeout 30 time python main.py /home/lulu/Documents/noctyra_security_audit/poc_02_dos_bigint.py --output /home/lulu/Documents/noctyra_security_audit/outputs/poc_02_out.py)",
+      "Bash(echo \"EXIT:$?\")",
+      "Bash(timeout 60 bash -c \"time uv run python main.py /home/lulu/Documents/noctyra_security_audit/poc_01_dos_listcomp.py --output /home/lulu/Documents/noctyra_security_audit/outputs/poc_01_out.py\")"
+    ]
+  }
+}

noctyra-0.1.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

noctyra-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v6
+    
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+      with:
+        enable-cache: true
+
+    - name: Set up Python
+      run: uv python install
+
+    - name: Install dependencies
+      run: uv sync --all-extras --dev
+
+    - name: Run Ruff (Linter)
+      run: uv run ruff check .
+
+    - name: Run Mypy (Type Check)
+      run: uv run mypy . --ignore-missing-imports
+
+    - name: Run Tests
+      run: |
+        export PYTHONPATH=$PYTHONPATH:.
+        uv run pytest tests/

noctyra-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+
+# Personal files
+.bk

noctyra-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+    -   id: trailing-whitespace
+    -   id: end-of-file-fixer
+    -   id: check-yaml
+    -   id: check-added-large-files
+
+-   repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.9
+    hooks:
+    -   id: ruff
+        args: [ --fix ]
+    -   id: ruff-format
+
+-   repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.15.0
+    hooks:
+    -   id: mypy
+        additional_dependencies: [tokenize-rt==5.2.0, types-requests]
+        args: [--ignore-missing-imports]

noctyra-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

noctyra-0.1.0/CLAUDE.md

@@ -0,0 +1,50 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+Use `uv` for all package management:
+
+```bash
+uv sync                        # Install basic dependencies
+uv sync --all-extras --dev     # Install all dependencies including dev tools
+```
+
+| Task | Command |
+|------|---------|
+| Run | `python main.py <input_file> [--output out.py] [--iterations N] [--debug]` |
+| Test | `make test` → `uv run pytest tests/` |
+| Lint | `make lint` → `uv run ruff check .` |
+| Format | `make format` → `uv run black . && uv run ruff check . --fix` |
+| Typecheck | `make typecheck` → `uv run mypy . --ignore-missing-imports` |
+| Single test | `uv run pytest tests/test_transformers.py::TestName -v` |
+
+## Architecture
+
+Noctyra is an AST-based Python deobfuscation/transformation framework. It parses a Python source file, runs a pipeline of AST transformers iteratively until no changes occur (or a fixed iteration count), then formats and writes the result.
+
+**Execution flow:**
+
+```
+main.py → ast.parse() → TransformerPipeline → black.format_str() → output file
+```
+
+**TransformerPipeline** (`transformers/pipeline.py`) runs five transformers in sequence each iteration:
+
+1. **ConstsTransformer** (`constants.py`) — constant folding, encoding/compression calls (base64, zlib, brotli, etc.)
+2. **BasicFunctions** (`functions.py`) — `exec()` unrolling, evaluation of `ord`, `chr`, `int`, `str`, `bytes`, etc.
+3. **BasicAttributes** (`attributes.py`) — string/bytes method resolution (`.decode`, `.join`, `.hex`, etc.) when all arguments are constant
+4. **LCTransformer** (`listcomp.py`) — folds list comprehensions and generators into literal lists
+5. **ConditionSimplifier** (`condsimplifier.py`) — simplifies comparisons and chained boolean expressions
+
+**SafeEval** (`transformers/safe_eval.py`) is the core evaluation engine used by most transformers. It walks AST nodes to evaluate constant expressions safely, with hard resource limits (100,000 bytes max allocation, ±100,000 numeric range, whitelist of allowed operators/functions).
+
+**SharedUtils** (`utils/shared.py`) holds maps reused across transformers: operator functions, safe built-ins, and encoding/compression handlers (including third-party: brotli, zstd, blosc).
+
+## Key constraints
+
+- **Python ≥ 3.14** required (uses newer AST APIs).
+- SafeEval is intentionally restricted — never expand it without considering bypass risks. For untrusted input, run in an external sandbox.
+- Transformers must be **idempotent**: applying them twice should produce the same result as once.
+- Pre-commit hooks run ruff (lint + format) and mypy automatically on commit.

noctyra-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 0p4n1k <0p4n1k@mailfence.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

noctyra-0.1.0/Makefile

@@ -0,0 +1,21 @@
+.PHONY: test lint format typecheck help
+
+help:
+	@echo "Noctyra Development Commands"
+	@echo "  test       Run unit tests"
+	@echo "  lint       Check code style with ruff"
+	@echo "  format     Format code with black and ruff"
+	@echo "  typecheck  Run mypy type checking"
+
+test:
+	uv run pytest tests/
+
+lint:
+	uv run ruff check .
+
+format:
+	uv run black .
+	uv run ruff check . --fix
+
+typecheck:
+	uv run mypy . --ignore-missing-imports

noctyra-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: noctyra
+Version: 0.1.0
+Summary: A generic static Python deobfuscator based on AST transformations
+Project-URL: Homepage, https://github.com/0p4n1k/Noctyra
+Project-URL: Repository, https://github.com/0p4n1k/Noctyra
+Project-URL: Issues, https://github.com/0p4n1k/Noctyra/issues
+Author-email: 0p4n1k <0p4n1k@mailfence.com>
+License: MIT
+License-File: LICENSE
+Keywords: ast,deobfuscator,python,reverse-engineering,static-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: black>=26.3.1
+Requires-Dist: blosc>=1.11.4
+Requires-Dist: brotli>=1.2.0
+Requires-Dist: rich>=14.3.3
+Requires-Dist: zstd>=1.5.7.3
+Description-Content-Type: text/markdown
+
+# Noctyra
+
+![Noctyra Demo](assets/demo.gif)
+
+![Python Version](https://img.shields.io/badge/python-3.14%2B-blue)
+![Status](https://img.shields.io/badge/status-experimental-orange)
+
+Noctyra is an AST-based framework designed for code transformation and deobfuscation. It provides a modular pipeline to analyze and simplify Python source code by resolving complex expressions and logic.
+
+## Overview
+
+The project aims to provide a flexible environment for processing Python's Abstract Syntax Tree. By employing a sequence of pluggable transformers, Noctyra can:
+
+- Simplify nested logic and conditions.
+- Resolve static values and common encoding patterns.
+- Unroll dynamic execution blocks into readable code.
+- Optimize and clean up obfuscated constructs.
+
+## Getting Started
+
+### Prerequisites
+
+Ensure you have `uv` installed for dependency management.
+
+```bash
+uv sync
+```
+
+### Running the Pipeline
+
+To process a target script, use the following command:
+
+```bash
+python main.py <input_file> [options]
+```
+
+**Options:**
+- `file`: Path to the input Python file (required).
+- `--output`: File name for the transformed code (default: `out.py`).
+- `--iterations`: Set a fixed number of transformation passes (default: `0` for auto-detect).
+- `--max-iterations`: Limit the passes in auto mode (default: `100`).
+- `--debug`: Enable verbose logging for debugging transformations. (look sick)
+
+## Development
+
+This project uses `uv` for dependency management and a `Makefile` for common tasks.
+
+### Setup
+```bash
+uv sync --all-extras --dev
+```
+
+### Quality Control
+Before submitting a PR or pushing changes, ensure all checks pass:
+
+- **Run Tests**: `make test`
+- **Lint & Format**: `make format`
+- **Type Check**: `make typecheck`
+
+*(Windows users: These commands work automatically via `make.bat`.)*
+
+### CI/CD
+Automated checks are performed on every push via GitHub Actions, including linting with Ruff, type checking with Mypy, and unit testing with Pytest.
+
+## Security Notice
+
+Noctyra includes an internal evaluation engine with basic resource limits. However, when dealing with untrusted code, it is highly recommended to run the pipeline within an isolated environment (such as a container or sandbox) to prevent potential side effects or resource exhaustion.
+
+---

noctyra-0.1.0/README.md

@@ -0,0 +1,69 @@
+# Noctyra
+
+![Noctyra Demo](assets/demo.gif)
+
+![Python Version](https://img.shields.io/badge/python-3.14%2B-blue)
+![Status](https://img.shields.io/badge/status-experimental-orange)
+
+Noctyra is an AST-based framework designed for code transformation and deobfuscation. It provides a modular pipeline to analyze and simplify Python source code by resolving complex expressions and logic.
+
+## Overview
+
+The project aims to provide a flexible environment for processing Python's Abstract Syntax Tree. By employing a sequence of pluggable transformers, Noctyra can:
+
+- Simplify nested logic and conditions.
+- Resolve static values and common encoding patterns.
+- Unroll dynamic execution blocks into readable code.
+- Optimize and clean up obfuscated constructs.
+
+## Getting Started
+
+### Prerequisites
+
+Ensure you have `uv` installed for dependency management.
+
+```bash
+uv sync
+```
+
+### Running the Pipeline
+
+To process a target script, use the following command:
+
+```bash
+python main.py <input_file> [options]
+```
+
+**Options:**
+- `file`: Path to the input Python file (required).
+- `--output`: File name for the transformed code (default: `out.py`).
+- `--iterations`: Set a fixed number of transformation passes (default: `0` for auto-detect).
+- `--max-iterations`: Limit the passes in auto mode (default: `100`).
+- `--debug`: Enable verbose logging for debugging transformations. (look sick)
+
+## Development
+
+This project uses `uv` for dependency management and a `Makefile` for common tasks.
+
+### Setup
+```bash
+uv sync --all-extras --dev
+```
+
+### Quality Control
+Before submitting a PR or pushing changes, ensure all checks pass:
+
+- **Run Tests**: `make test`
+- **Lint & Format**: `make format`
+- **Type Check**: `make typecheck`
+
+*(Windows users: These commands work automatically via `make.bat`.)*
+
+### CI/CD
+Automated checks are performed on every push via GitHub Actions, including linting with Ruff, type checking with Mypy, and unit testing with Pytest.
+
+## Security Notice
+
+Noctyra includes an internal evaluation engine with basic resource limits. However, when dealing with untrusted code, it is highly recommended to run the pipeline within an isolated environment (such as a container or sandbox) to prevent potential side effects or resource exhaustion.
+
+---

noctyra-0.1.0/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported Versions
+
+The following versions of Noctyra are currently supported with security updates:
+
+| Version | Supported          
+| ------- | ------------------ 
+| 0.1.x   | ✅               
+
+## Reporting a Vulnerability
+
+We take the security of Noctyra's `SafeEval` and AST transformation process seriously. If you find a way to achieve arbitrary code execution during the transformation phase (bypassing the evaluation guards), please report it responsibly.
+
+**Do not open an issue on GitHub.** Please report vulnerabilities through the following method:
+
+1. Send an email to [0p4n1k@mailfence.com]
+2. Include a proof-of-concept (PoC) payload.
+3. Describe the impact and the environment (Python version, OS).
+
+We will respond within 48 hours and coordinate a fix.

noctyra-0.1.0/classes/Context.py

@@ -0,0 +1,75 @@
+from .Function import CustomFunction
+from .Variable import Variable, supported_types
+import ast
+
+
+class Context:
+    def __init__(self, vars=None):
+        self.vars: list[Variable] = vars or []
+
+    def get(self, name: str):
+        for var in self.vars:
+            if var.name == name and var.has_value():
+                return var
+
+        return None
+
+    def has(self, name: str):
+        return any(var.name == name for var in self.vars)
+
+    def set(self, name: str, value):
+
+        for var in self.vars:
+            if var.name == name:
+                var.set(value=value)
+                return
+
+        self.vars.append(Variable(name=name, value=value))
+
+    def copy_with(self, vars: list[Variable]):
+        new = Context(vars=self.vars.copy())
+        new.vars.extend(vars)
+        return new
+
+    def invalidate(self, name: str) -> None:
+        self.vars = [v for v in self.vars if v.name != name]
+
+    @staticmethod
+    def from_tree(tree: ast.AST) -> "Context":
+        ctx = Context()
+
+        for node in ast.iter_child_nodes(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                continue
+
+            if isinstance(node, (ast.Assign, ast.AnnAssign, ast.NamedExpr)):
+                try:
+                    if node.value is None:
+                        continue
+                    targets = (
+                        node.targets if isinstance(node, ast.Assign) else [node.target]
+                    )
+
+                    if not all(isinstance(t, ast.Name) for t in targets):
+                        continue
+                    if isinstance(node.value, ast.Lambda):
+                        value = CustomFunction(node.value.body, node.value.args)
+
+                    else:
+                        value = ast.literal_eval(node.value)
+
+                    if isinstance(value, supported_types):
+                        for target in targets:
+                            if isinstance(target, ast.Name):
+                                ctx.set(target.id, value)
+
+                except ValueError:
+                    pass
+
+            elif isinstance(node, ast.AugAssign):
+                if not isinstance(node.target, ast.Name):
+                    continue
+
+                ctx.invalidate(node.target.id)
+
+        return ctx

noctyra-0.1.0/classes/Function.py

@@ -0,0 +1,7 @@
+import ast
+
+
+class CustomFunction:
+    def __init__(self, body: ast.AST, args: ast.arguments) -> None:
+        self.body = body
+        self.args = args

noctyra-0.1.0/classes/Variable.py

@@ -0,0 +1,35 @@
+from .Function import CustomFunction
+
+supported_types = int | float | str | bool | bytes | list | dict | set | CustomFunction
+supported_iterator = str | bytes | dict | list | set
+
+
+class Variable:
+    def __init__(self, name, value):
+
+        if not isinstance(name, str):
+            raise ValueError(f"Variable name must be a string. {name=}, {value=}")
+
+        if not isinstance(value, supported_types):
+            raise ValueError(f"Unsupported variable type. {name=}, {value=}")
+
+        self.name = name
+        self.value = value
+
+    def has_value(self):
+        return self.value is not None
+
+    def set(self, *, value):
+
+        if not isinstance(value, supported_types) and value is not None:
+            raise ValueError(
+                f"Unsupported variable type: {type(value).__name__}. {self.name=}, {value=}"
+            )
+
+        self.value = value
+
+    def get(self) -> supported_types:
+        return self.value
+
+    def __repr__(self):
+        return f"Variable(name={self.name}, value={self.value})"

noctyra-0.1.0/classes/__init__.py

@@ -0,0 +1,5 @@
+from .Context import Context
+from .Variable import Variable, supported_types
+from .Function import CustomFunction
+
+__all__ = ["Context", "Variable", "CustomFunction", "supported_types"]

noctyra-0.1.0/main.py

@@ -0,0 +1,100 @@
+from transformers import (
+    ConstsTransformer,
+    BasicFunctions,
+    BasicAttributes,
+    LCTransformer,
+    ConditionSimplifier,
+    NameReplacer,
+    DeadCodeRemover,
+)
+from transformers import TransformerPipeline
+from utils.logger import LOGGER
+import argparse
+import black
+import ast
+
+
+def main():
+    argparser = argparse.ArgumentParser(
+        description="Transform Python code using AST transformers."
+    )
+    argparser.add_argument("file", help="Path to the Python file to transform.")
+    argparser.add_argument(
+        "--iterations",
+        type=int,
+        default=0,
+        help="Number of iterations to apply the transformers. Default is 0 (auto).",
+    )
+    argparser.add_argument(
+        "--max-iterations",
+        type=int,
+        default=100,
+        help="Maximum iterations when using auto mode. Default is 100.",
+    )
+    argparser.add_argument(
+        "--max-depth",
+        type=int,
+        default=50,
+        help="Maximum depth when inspecting recursive function. Default is 50.",
+    )
+    argparser.add_argument(
+        "--max-allocation",
+        type=int,
+        default=100_000,
+        help="Maximum allocation to prevent DOS. Default is 100000.",
+    )
+    argparser.add_argument(
+        "--output",
+        type=str,
+        default="out.py",
+        help="Output file for the transformed code. Default is out.py.",
+    )
+    argparser.add_argument("--debug", action="store_true", help="Enable debug logging.")
+    argparser.add_argument(
+        "--stdout", action="store_true", help="Output transformed code to stdout."
+    )
+
+    args = argparser.parse_args()
+
+    if args.debug:
+        LOGGER.setLevel("DEBUG")
+
+    with open(args.file, "r", encoding="utf-8") as f:
+        code = f.read()
+
+    tree = ast.parse(code)
+
+
+    pipeline = TransformerPipeline(
+        transformers=[
+            ConstsTransformer,
+            BasicFunctions,
+            BasicAttributes,
+            LCTransformer,
+            ConditionSimplifier,
+            NameReplacer,
+            DeadCodeRemover,
+        ],
+        iterations=args.iterations,
+        max_iterations=args.max_iterations,
+        max_depth=args.max_depth,
+        max_allocation=args.max_allocation,
+    )
+
+    result = pipeline.visit(tree)
+
+    new_code = ast.unparse(result)
+
+    res = black.format_str(new_code, mode=black.Mode())
+
+    with open(args.output, "w", encoding="utf-8") as f:
+        f.write(res)
+
+    LOGGER.debug(f"Output written to {args.output}")
+
+    if args.stdout:
+        print(res)
+
+
+if __name__ == "__main__":
+    main()

noctyra-0.1.0/make.bat

@@ -0,0 +1,21 @@
+@echo off
+if "%1"=="test" (
+    uv run pytest tests/
+    exit /b %ERRORLEVEL%
+) else if "%1"=="lint" (
+    uv run ruff check .
+    exit /b %ERRORLEVEL%
+) else if "%1"=="format" (
+    uv run ruff format .
+    uv run ruff check . --fix
+    exit /b %ERRORLEVEL%
+) else if "%1"=="typecheck" (
+    uv run mypy . --ignore-missing-imports
+    exit /b %ERRORLEVEL%
+) else (
+    echo Noctyra Development Commands (Windows)
+    echo   make test       - Run unit tests
+    echo   make lint       - Check code style with ruff
+    echo   make format     - Format code with ruff
+    echo   make typecheck  - Run mypy type checking
+)