0
# PyMISP
1

2
A comprehensive Python library for programmatic access to MISP (Malware Information Sharing Platform) instances via their REST API. PyMISP enables cybersecurity professionals to automate threat intelligence sharing, manage events and attributes, perform complex searches, and integrate MISP functionality into security workflows.
3

4
## Package Information
5

6
- **Package Name**: pymisp
7
- **Language**: Python  
8
- **Installation**: `pip install pymisp`
9
- **Optional Dependencies**: `pip install pymisp[fileobjects,virustotal,email,pdfexport]`
10

11
## Core Imports
12

13
```python
14
from pymisp import PyMISP
15
```
16

17
For specific components:
18

19
```python
20
from pymisp import (
21
    PyMISP, MISPEvent, MISPAttribute, MISPObject, 
22
    MISPUser, MISPOrganisation, MISPTag
23
)
24
```
25

26
## Basic Usage
27

28
```python
29
from pymisp import PyMISP, MISPEvent, MISPAttribute
30

31
# Initialize PyMISP client
32
misp = PyMISP('https://your-misp-instance.com', 'your-api-key', ssl=True)
33

34
# Get recent events
35
events = misp.search(timestamp='5d', limit=10)
36

37
# Create a new event
38
event = MISPEvent()
39
event.info = "Suspicious Activity Detected"
40
event.distribution = 1  # Community only
41
event.threat_level_id = 2  # Medium
42

43
# Add event to MISP
44
response = misp.add_event(event)
45

46
# Add an attribute
47
attribute = MISPAttribute()
48
attribute.type = 'ip-dst'
49
attribute.value = '192.168.1.100'
50
attribute.comment = 'Malicious IP address'
51

52
misp.add_attribute(event_id, attribute)
53

54
# Search for specific indicators
55
results = misp.search(value='192.168.1.100', type_attribute='ip-dst')
56
```
57

58
## Architecture
59

60
PyMISP provides a multi-layered architecture for MISP interaction:
61

62
- **PyMISP Client**: Main API interface handling authentication and HTTP communication
63
- **Data Model Objects**: Rich Python objects representing MISP entities (events, attributes, objects, users)
64
- **Object Generators**: Specialized tools for creating structured threat intelligence objects
65
- **Search & Filter System**: Comprehensive querying capabilities across all MISP data types
66
- **Synchronization Tools**: Multi-server data sharing and federation support
67

68
This design enables both simple one-off queries and complex automated threat intelligence workflows.
69

70
## Capabilities
71

72
### Core API Client
73

74
The main PyMISP class providing comprehensive REST API access to MISP instances, including event management, searching, user administration, and server synchronization.
75

76
```python { .api }
77
class PyMISP:
78
    def __init__(self, url: str, key: str, ssl: bool = True, debug: bool = False) -> None: ...
79
    
80
    # Properties
81
    @property
82
    def version(self) -> str: ...
83
    @property
84
    def misp_instance_version(self) -> dict: ...
85
```
86

87
[Core API Client](./core-api.md)
88

89
### Event Management
90

91
Comprehensive event lifecycle management including creation, modification, publishing, and deletion of MISP events with full attribute and object support.
92

93
```python { .api }
94
def events(self, **kwargs) -> list: ...
95
def get_event(self, event_id: int | str, **kwargs) -> dict: ...
96
def add_event(self, event: MISPEvent | dict, **kwargs) -> dict: ...
97
def update_event(self, event: MISPEvent | dict, **kwargs) -> dict: ...
98
def delete_event(self, event_id: int | str) -> dict: ...
99
def publish(self, event_id: int | str) -> dict: ...
100
```
101

102
[Event Management](./event-management.md)
103

104
### Attribute Management
105

106
Detailed attribute handling for managing indicators and observables within events, including attribute creation, updates, and validation.
107

108
```python { .api }
109
def attributes(self, **kwargs) -> list: ...
110
def get_attribute(self, attribute_id: int | str) -> dict: ...
111
def add_attribute(self, event_id: int | str, attribute: MISPAttribute | dict, **kwargs) -> dict: ...
112
def update_attribute(self, attribute: MISPAttribute | dict, **kwargs) -> dict: ...
113
def delete_attribute(self, attribute_id: int | str) -> dict: ...
114
```
115

116
[Attribute Management](./attribute-management.md)
117

118
### Object Management
119

120
MISP object handling for structured threat intelligence data including file objects, network objects, and custom object types.
121

122
```python { .api }
123
def get_object(self, object_id: int | str) -> dict: ...
124
def add_object(self, event_id: int | str, misp_object: MISPObject | dict, **kwargs) -> dict: ...
125
def update_object(self, misp_object: MISPObject | dict, **kwargs) -> dict: ...
126
def delete_object(self, object_id: int | str) -> dict: ...
127
def object_templates(self) -> list: ...
128
```
129

130
[Object Management](./object-management.md)
131

132
### Search & Query
133

134
Powerful search capabilities across events, attributes, sightings, and other MISP data with complex filtering and correlation support.
135

136
```python { .api }
137
def search(self, **kwargs) -> list: ...
138
def search_index(self, **kwargs) -> list: ...
139
def search_sightings(self, **kwargs) -> list: ...
140
def search_logs(self, **kwargs) -> list: ...
141
def search_tags(self, **kwargs) -> list: ...
142
```
143

144
[Search & Query](./search-query.md)
145

146
### Data Model Classes
147

148
Rich Python objects representing all MISP entities with validation, serialization, and relationship management capabilities.
149

150
```python { .api }
151
class MISPEvent(AbstractMISP): ...
152
class MISPAttribute(AbstractMISP): ...
153
class MISPObject(AbstractMISP): ...
154
class MISPUser(AbstractMISP): ...
155
class MISPOrganisation(AbstractMISP): ...
156
```
157

158
[Data Model Classes](./data-models.md)
159

160
### User & Organization Management
161

162
Complete user account and organization administration including roles, permissions, and settings management.
163

164
```python { .api }
165
def users(self, **kwargs) -> list: ...
166
def get_user(self, user_id: int | str) -> dict: ...
167
def add_user(self, user: MISPUser | dict, **kwargs) -> dict: ...
168
def organisations(self, **kwargs) -> list: ...
169
def get_organisation(self, org_id: int | str) -> dict: ...
170
```
171

172
[User & Organization Management](./user-org-management.md)
173

174
### Object Generators & Tools
175

176
Specialized object creation tools for generating structured threat intelligence objects from various data sources.
177

178
```python { .api }
179
class FileObject(AbstractMISPObjectGenerator): ...
180
class URLObject(AbstractMISPObjectGenerator): ...
181
class EmailObject(AbstractMISPObjectGenerator): ...
182
class VTReportObject(AbstractMISPObjectGenerator): ...
183
```
184

185
[Object Generators & Tools](./object-generators.md)
186

187
### Server & Synchronization
188

189
Multi-server synchronization and federation capabilities for sharing threat intelligence across MISP instances.
190

191
```python { .api }
192
def servers(self, **kwargs) -> list: ...
193
def add_server(self, server: MISPServer | dict) -> dict: ...
194
def server_pull(self, server_id: int | str, **kwargs) -> dict: ...
195
def server_push(self, server_id: int | str, **kwargs) -> dict: ...
196
```
197

198
[Server & Synchronization](./server-sync.md)
199

200
### Tag & Taxonomy Management
201

202
Comprehensive tagging and classification system management including taxonomies, warning lists, and custom tags.
203

204
```python { .api }
205
def tags(self, **kwargs) -> list: ...
206
def add_tag(self, tag: MISPTag | dict, **kwargs) -> dict: ...
207
def taxonomies(self, **kwargs) -> list: ...
208
def warninglists(self, **kwargs) -> list: ...
209
```
210

211
[Tag & Taxonomy Management](./tag-taxonomy.md)