0
# YARA Python Interface
1

2
YARA-Python provides Python bindings for YARA (Yet Another Recursive Acronym), a powerful malware identification and classification tool. It enables Python developers to compile YARA rules, scan files, memory, and processes for pattern matches, and handle malware detection workflows within Python applications.
3

4
## Package Information
5

6
- **Package Name**: yara-python
7
- **Package Type**: pypi
8
- **Language**: Python (C extension)
9
- **Installation**: `pip install yara-python`
10
- **License**: Apache 2.0
11
- **Platform Support**: Windows, macOS, Linux, FreeBSD, OpenBSD
12

13
## Core Imports
14

15
```python
16
import yara
17
```
18

19
## Basic Usage
20

21
```python
22
import yara
23

24
# Compile YARA rules from source
25
rules = yara.compile(source='''
26
rule TestRule {
27
    strings:
28
        $text = "malicious"
29
    condition:
30
        $text
31
}
32
''')
33

34
# Scan data for matches
35
matches = rules.match(data="This contains malicious content")
36

37
# Process results
38
for match in matches:
39
    print(f"Rule {match.rule} matched!")
40
    for offset, identifier, data in match.strings:
41
        print(f"  Found '{data}' at offset {offset}")
42

43
# Save compiled rules for reuse
44
rules.save(filepath="compiled_rules.yarc")
45

46
# Load previously compiled rules
47
loaded_rules = yara.load(filepath="compiled_rules.yarc")
48
```
49

50
## Architecture
51

52
YARA-Python follows a three-layer architecture:
53

54
- **Compilation Layer**: Compiles textual YARA rules into optimized Rules objects
55
- **Scanning Layer**: Applies compiled rules to various data sources (files, memory, processes)  
56
- **Results Layer**: Provides structured access to match results with rule metadata
57

58
The package supports both static and dynamic linking against the YARA library, with optional modules for enhanced functionality including magic file type detection, PE/Mach-O/DEX executable parsing, and Cuckoo sandbox integration.
59

60
## Capabilities
61

62
### Rule Compilation and Loading
63

64
Compile YARA rules from various sources (strings, files, file-like objects) with support for external variables, include callbacks, and namespace organization. Save and load compiled rules for performance optimization.
65

66
```python { .api }
67
def compile(source=None, filepath=None, file=None, filepaths=None, sources=None, 
68
           includes=True, externals=None, error_on_warning=False, include_callback=None): ...
69
def load(filepath=None, file=None): ...
70
```
71

72
[Rule Compilation and Loading](./compilation.md)
73

74
### Pattern Matching and Scanning
75

76
Scan files, memory buffers, and running processes with compiled YARA rules. Support for callbacks, timeouts, external variables, and module-specific data processing.
77

78
```python { .api }
79
class Rules:
80
    def match(self, filepath=None, pid=None, data=None, externals=None, callback=None,
81
              fast=False, timeout=60, modules_data=None, modules_callback=None, 
82
              which_callbacks=None): ...
83
```
84

85
[Pattern Matching and Scanning](./matching.md)
86

87
### Configuration and Error Handling
88

89
Configure YARA engine parameters and handle various error conditions including syntax errors, timeouts, and warnings with structured exception hierarchy.
90

91
```python { .api }
92
def set_config(stack_size=None, max_strings_per_rule=None): ...
93

94
class Error(Exception): ...
95
class SyntaxError(Error): ...
96
class TimeoutError(Error): ...
97
class WarningError(Error): ...
98
```
99

100
[Configuration and Error Handling](./config.md)
101

102
## Version Information
103

104
```python { .api }
105
__version__: str        # YARA library version string
106
YARA_VERSION: str      # YARA library version string  
107
YARA_VERSION_HEX: int  # YARA library version as hexadecimal
108
```
109

110
## Types
111

112
```python { .api }
113
class Rules:
114
    """Compiled YARA rules container supporting iteration."""
115
    def match(self, filepath=None, pid=None, data=None, externals=None, callback=None,
116
              fast=False, timeout=60, modules_data=None, modules_callback=None, 
117
              which_callbacks=None): ...
118
    def save(self, filepath=None, file=None): ...
119
    def profiling_info(self): ...
120
    def __iter__(self): ...  # Iterate over Rule objects
121

122
class Rule:
123
    """Individual YARA rule representation."""
124
    identifier: str  # Rule name/identifier
125
    tags: list      # List of rule tags
126
    meta: dict      # Rule metadata dictionary
127

128
class Match:
129
    """Represents a rule match result."""
130
    rule: str        # Name of the matching rule
131
    namespace: str   # Namespace of the matching rule
132
    tags: list       # Tags associated with the rule
133
    meta: dict       # Metadata dictionary from the rule
134
    strings: list    # List of (offset, identifier, data) tuples
135
```
136

137
## Constants
138

139
```python { .api }
140
# Callback control constants
141
CALLBACK_CONTINUE: int = 0     # Continue processing in callbacks
142
CALLBACK_ABORT: int = 1        # Abort processing in callbacks
143
CALLBACK_MATCHES: int = 0x01   # Callback for matching rules only
144
CALLBACK_NON_MATCHES: int = 0x02  # Callback for non-matching rules only
145
CALLBACK_ALL: int = 0x03       # Callback for all rules
146
```