boreal-python 0.1.0__cp311-abi3-win_amd64.whl

boreal/__init__.py

@@ -0,0 +1,5 @@
+from .boreal import *
+
+__doc__ = boreal.__doc__
+if hasattr(boreal, "__all__"):
+    __all__ = boreal.__all__

boreal/__init__.pyi

@@ -0,0 +1,291 @@
+from typing import Any, Callable, Protocol, TypeAlias, TypedDict, final
+from collections import abc
+
+
+def compile(
+    filepath: str | None = None,
+    filepaths: dict[str, str] | None = None,
+    source: str | None = None,
+    sources: dict[str, str] | None = None,
+    file: Readable | None = None,
+
+    externals: dict[str, ExternalValue] | None = None,
+    includes: bool = True,
+    error_on_warning: bool = False,
+    include_callback: IncludeCallback | None = None,
+    strict_escape: bool | None = None,
+    profile: CompilerProfile | None = None,
+) -> Scanner: ...
+
+def load(
+    filepath: str | None = None,
+    file: Readable | None = None,
+    data: bytes | None = None,
+) -> Scanner: ...
+
+def set_config(
+    max_strings_per_rule: int | None = None,
+    max_match_data: int | None = None,
+    stack_size: int | None = None,
+    yara_compatibility: bool | None = None,
+) -> None: ...
+
+modules: list[str]
+"""List of availables modules"""
+
+class Error(Exception): ...
+class AddRuleError(Error): ...
+class SyntaxError(Error): ...
+class ScanError(Error): ...
+class TimeoutError(Error): ...
+
+
+@final
+class Rule:
+    identifier: str
+    namespace: str
+    tags: list[str]
+    meta: dict[str, MetadataValue]
+    is_global: bool
+    is_private: bool
+
+
+@final
+class Match:
+    rule: str
+    namespace: str
+    meta: dict[str, MetadataValue]
+    tags: list[str]
+    strings: list[StringMatches]
+
+    def __le__(self, other: object) -> bool: ...
+    def __eq__(self, other: object) -> bool: ...
+    def __ne__(self, other: object) -> bool: ...
+    def __gt__(self, other: object) -> bool: ...
+    def __ge__(self, other: object) -> bool: ...
+
+    def __hash__(self) -> int: ...
+
+
+@final
+class Scanner(abc.Iterable[Rule]):
+    warnings: list[str]
+
+    def match(
+        self,
+        filepath: str | None = None,
+        data: str | bytes | None = None,
+        pid: int | None = None,
+        externals: dict[str, ExternalValue] | None = None,
+        callback: MatchCallback | None = None,
+        # TODO: improve type
+        which_callbacks: int | None = None,
+        fast: bool | None = None,
+        timeout: int | None = None,
+        modules_data: dict[str, Any] | None = None,
+        modules_callback: ModulesCallback | None = None,
+        warnings_callback: WarningCallback | None = None,
+        console_callback: ConsoleCallback | None = None,
+        allow_duplicate_metadata: bool | None = False,
+    ) -> list[Match]: ...
+
+    def save(
+        self,
+        filepath: str | None = None,
+        file: Writable | None = None,
+        to_bytes: bool = False
+    ) -> bytes | None: ...
+
+    def set_params(
+        self,
+        use_mmap: bool | None = None,
+        string_max_nb_matches: int | None = None,
+        fragmented_scan_mode: str | None = None,
+        process_memory: bool | None = None,
+        max_fetched_region_size: int | None = None,
+        memory_chunk_size: int | None = None,
+    ) -> None: ...
+
+    def __iter__(self) -> RulesIter: ...
+
+
+@final
+class RulesIter(abc.Iterator[Rule]):
+    def __iter__(self) -> RulesIter: ...
+    def __next__(self) -> Rule: ...
+
+
+@final
+class StringMatchInstance:
+    offset: int
+    matched_data: bytes
+    matched_length: int
+    xor_key: int
+
+    def plaintext(self) -> bytes: ...
+
+    def __hash__(self) -> int: ...
+
+
+@final
+class StringMatches:
+    identifier: str
+    instances: list[StringMatchInstance]
+
+    def is_xor(self) -> bool: ...
+
+    def __hash__(self) -> int: ...
+
+
+@final
+class RuleString:
+    namespace: str
+    rule: str
+    string: str
+
+
+@final
+class CompilerProfile:
+    Speed: 'CompilerProfile'
+    Memory: 'CompilerProfile'
+
+
+class RuleDetails(TypedDict):
+    """Details about a rule passed to the match callback."""
+
+    rule: str
+    """Name of the matching rule"""
+    namespace: str
+    """Namespace of the matching rule"""
+    meta: dict[str, MetadataValue]
+    """List of tags associated to the rule"""
+    tags: list[str]
+    """Dictionary with metadata associated to the rule"""
+    strings: list[StringMatches]
+    """Details about the string matches of the rule"""
+    matches: bool
+    """Did the rule match"""
+
+
+__version__: str
+"""Version of the boreal-py library"""
+
+CALLBACK_CONTINUE: int
+"""Return value used in callbacks to signal the scan must continue.
+
+Callbacks used in the [`match`](api.md#boreal.Scanner.match) method should return
+this value to keep the scan going.
+"""
+
+CALLBACK_ABORT: int
+"""Return value used in callbacks to abort the scan.
+
+Callbacks used in the [`match`](api.md#boreal.Scanner.match) method should return
+this value to abort the scan. If the scan is aborted, the match method will
+not raise any exception but will end immediately, returning the results it
+has computed so far.
+"""
+
+CALLBACK_MATCHES: int
+"""Call the match callback when a rule matches.
+
+If specified in the `which_callbacks` parameter of the
+[`match`](api.md#boreal.Scanner.match) method, the callback will be
+called when a rule matches.
+"""
+
+CALLBACK_NON_MATCHES: int
+"""Call the match callback when a rule does not match.
+
+If specified in the `which_callbacks` parameter of the
+[`match`](api.md#boreal.Scanner.match) method, the callback will be
+called when a rule does not match.
+"""
+
+CALLBACK_ALL: int
+"""Call the match callback after a rule is evaluated.
+
+If specified in the `which_callbacks` parameter of the
+[`match`](api.md#boreal.Scanner.match) method the callback will be called
+after a is evaluated, regardless of whether it has matched or not. the
+[`matches`](api.md#boreal.RuleDetails.matches) attribute of the passed rule
+can be used to know if the rule has matched or not.
+"""
+
+CALLBACK_TOO_MANY_MATCHES: int
+"""A string has had too many matches.
+
+This is used in the `warnings_callback` of the [`match`](#boreal.Scanner.match)
+method to indicate the warning kind.
+"""
+
+CallbackResult: TypeAlias = int
+"""Return status that can be returned by a callback.
+
+This must be one of:
+
+  - [`CALLBACK_CONTINUE`](api.md#CALLBACK_CONTINUE)
+
+  - [`CALLBACK_ABORT`](api.md#boreal.CALLBACK_ABORT)
+"""
+
+WarningType: TypeAlias = int
+"""Type of warning passed to the warning callback.
+
+This can be one of:
+
+  - [`CALLBACK_TOO_MANY_MATCHES`](api.md#boreal.CALLBACK_TOO_MANY_MATCHES):
+    the associated data is a [`RuleString`](api.md#boreal.RuleString).
+"""
+
+ConsoleCallback: TypeAlias = Callable[[str], None]
+"""Callback handling uses of the `console` module in rules.
+
+It receives the log as the lone argument.
+"""
+
+MatchCallback: TypeAlias = Callable[[RuleDetails], CallbackResult]
+"""Callback called when rules are evaluated."""
+
+ModulesCallback: TypeAlias = Callable[[dict[str, Any]], CallbackResult]
+"""Callback called when a module is evaluated.
+
+The callback receives the dynamic values of the module as the first
+argument. The name of the module is accessible with the `"module"` key.
+"""
+
+WarningCallback: TypeAlias = Callable[[WarningType, RuleString], CallbackResult]
+"""Callback called when a warning is emitted during a scan."""
+
+MetadataValue: TypeAlias = bytes | int | bool
+"""The value of a metadata key declared in a rule."""
+
+ExternalValue: TypeAlias = str | bytes | int | float | bool
+"""The value of an external symbol usable in a rule condition."""
+
+IncludeCallback: TypeAlias = Callable[[str, str | None, str], str]
+"""Callback used to resolve include directives.
+
+Receive three arguments:
+
+  - The path being included.
+
+  - The path of the current document. Can be None if the current
+    document was specified as a string, such as when using the
+    `source` or `sources` parameter.
+
+  - The current namespace.
+
+Must return a string which is the included document.
+"""
+
+class Readable(Protocol):
+    """A readable object"""
+
+    def read(self) -> str: ...
+
+class Writable(Protocol):
+    """A writable object"""
+
+    def write(self, data: bytes) -> int: ...
+    def flush(self) -> None: ...

boreal_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: boreal-python
+Version: 0.1.0
+Summary: Python bindings to the boreal YARA scanner
+Keywords: boreal,yara,string-matching,scan,python
+License: MIT OR Apache-2.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Source Code, https://github.com/vthib/boreal
+
+# Python bindings for the boreal YARA scanner
+
+The library allows using the [boreal](https://github.com/vthib/boreal) library
+to scan files and processes using YARA rules.
+
+```py
+import boreal
+
+scanner = boreal.compile(source="""
+rule example {
+    meta:
+        description = "This is an YARA rule example"
+        date = "2022-11-11"
+    strings:
+        $s1 = { 78 6d 6c 68 74 74 70 2e 73 65 6e 64 28 29 }
+        $s2 = "tmp.dat" fullword wide
+    condition:
+        any of them
+}
+""");
+
+results = scanner.match(data=b"<\0t\0m\0p\0.\0d\0a\0t\0>\0")
+assert [rule.name for rule in results] == ["example"]
+```
+
+## Description
+
+This library can serve as a drop-in replacement of the YARA python library,
+while also providing improvements and saner default behavior.
+
+- Literal replacement to the yara library:
+  replace `import yara` with `import boreal` and everything will work.
+
+- Saner default behavior compared to the yara library: fast scanning enabled
+  by default, proper hash implementations of python objects, use of the bytes
+  type in some places to avoid losing information, etc.
+
+- 100% compatibility with the yara library guaranteed if needed through
+  a yara compatibility mode.
+
+## Yara compatibility
+
+This library guarantees 100% compatibility with the YARA library: the whole API
+is entirely tested against both libraries to guarantee perfect compatibility.
+
+However, a few differences are introduced in the default behavior of this library
+to ensure that this default behavior fixes some issues in the behavior of the yara
+library. Those changes are minimal, but can introduce breakage when replacing
+the yara library.
+
+Therefore, you can either:
+
+- Use the compatibility mode to ensure 100% compatibility with the yara library:
+
+```py
+import boreal
+
+boreal.set_config(yara_compatibility=True)
+```
+
+This guarantees that the yara library can be replaced and nothing will break.
+However, it also keeps alive a few issues in this library. It is therefore
+only recommended to enable this mode when replacing the yara library and wanting
+to ensure that nothing can break.
+
+- Use boreal as is. This fixes a few issues while still providing almost
+  entirely the same API.
+
+This is recommended if using this library from scratch, or when all the uses
+of the yara library can be easily checked to ensure nothing will break.
+
+For a description of all the differences that exists when the compatibility mode
+is not enabled, you can consult [this documentation](https://vthib.github.io/boreal/boreal-py/dev/yara_compatibility_mode/).
+

boreal_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+boreal/__init__.py,sha256=7pK5mFoG5aGo1_qWJrjD6PJK2WQeo8-Epqelbf2G6Z4,107
+boreal/__init__.pyi,sha256=_c9UZrqKNp-Cv8VRdfZPseSw37vyR6VyJQunRYD2Hq0,8117
+boreal/boreal.pyd,sha256=au5f9HR5-vUZthVt7AVErydBthqSi9FAoJs5yEsPh54,5009920
+boreal/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+boreal_python-0.1.0.dist-info/METADATA,sha256=OYz1ija9JWpaEPXzcCPuvhU1ck2tWrhBVRzJOPCA65M,2953
+boreal_python-0.1.0.dist-info/WHEEL,sha256=Xdqe9WTKNY7ZeOsCAPAyf3vP9c04Nzn-WHIZ9sIpX4E,95
+boreal_python-0.1.0.dist-info/RECORD,,

boreal_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.8.6)
+Root-Is-Purelib: false
+Tag: cp311-abi3-win_amd64