0
# Search & Query
1

2
Powerful search capabilities across events, attributes, sightings, and other MISP data with complex filtering, correlation support, and advanced query options.
3

4
## Capabilities
5

6
### General Search
7

8
Comprehensive search across all MISP data types with flexible filtering and correlation.
9

10
```python { .api }
11
def search(
12
    self,
13
    controller: str = 'events',
14
    return_format: str = 'json',
15
    limit: int = None,
16
    page: int = None,
17
    value: Union[str, List[str]] = None,
18
    type_attribute: Union[str, List[str]] = None,
19
    category: Union[str, List[str]] = None,
20
    org: Union[str, int, List] = None,
21
    tags: Union[str, List[str]] = None,
22
    not_tags: Union[str, List[str]] = None,
23
    date_from: Union[str, datetime] = None,
24
    date_to: Union[str, datetime] = None,
25
    last: str = None,
26
    eventid: Union[str, int, List] = None,
27
    with_attachments: bool = None,
28
    metadata: bool = None,
29
    uuid: Union[str, List[str]] = None,
30
    publish_timestamp: Union[str, int] = None,
31
    timestamp: Union[str, int, List] = None,
32
    enforceWarninglist: bool = None,
33
    to_ids: bool = None,
34
    deleted: bool = False,
35
    include_event_uuid: bool = None,
36
    include_event_tags: bool = None,
37
    event_timestamp: Union[str, int] = None,
38
    sg_reference_only: bool = None,
39
    eventinfo: str = None,
40
    searchall: str = None,
41
    requested_attributes: List[str] = None,
42
    include_context: bool = None,
43
    headerless: bool = None,
44
    include_sightings: bool = None,
45
    include_correlations: bool = None,
46
    include_decay_score: bool = None,
47
    decayingModel: Union[str, int, List] = None,
48
    exclude_decayed: bool = None,
49
    score: int = None,
50
    **kwargs
51
) -> Union[List, Dict]:
52
    """
53
    Perform comprehensive search across MISP data.
54
    
55
    Parameters:
56
    - controller: Search target ('events', 'attributes', 'objects')
57
    - return_format: Output format ('json', 'xml', 'csv', 'stix', 'stix2', 'yara', etc.)
58
    - limit: Maximum results to return
59
    - page: Page number for pagination
60
    - value: Search by attribute values (supports wildcards)
61
    - type_attribute: Filter by attribute types
62
    - category: Filter by attribute categories
63
    - org: Filter by organization ID/name
64
    - tags: Include only items with these tags
65
    - not_tags: Exclude items with these tags
66
    - date_from: Start date for search range
67
    - date_to: End date for search range
68
    - last: Time range (e.g., '5d', '2h', '30m')
69
    - eventid: Filter by specific event IDs
70
    - with_attachments: Include only items with attachments
71
    - metadata: Return metadata only (faster)
72
    - uuid: Filter by specific UUIDs
73
    - publish_timestamp: Filter by publish time
74
    - timestamp: Filter by modification time
75
    - enforceWarninglist: Apply warning list filtering
76
    - to_ids: Filter by IDS export flag
77
    - deleted: Include deleted items
78
    - include_event_uuid: Include event UUID in results
79
    - include_event_tags: Include event tags in results
80
    - event_timestamp: Filter by event timestamp
81
    - sg_reference_only: Sharing group reference only
82
    - eventinfo: Search in event info field
83
    - searchall: Search across all fields
84
    - requested_attributes: Specific attributes to return
85
    - include_context: Include contextual information
86
    - headerless: Return results without headers
87
    - include_sightings: Include sighting data
88
    - include_correlations: Include correlation data
89
    - include_decay_score: Include decay scoring
90
    - decayingModel: Specific decaying models to use
91
    - exclude_decayed: Exclude decayed indicators
92
    - score: Minimum decay score threshold
93
    
94
    Returns:
95
    Search results in specified format
96
    """
97

98
def search_index(
99
    self,
100
    all: str = None,
101
    attribute: str = None,
102
    email: str = None,
103
    published: bool = None,
104
    hasproposal: bool = None,
105
    eventid: Union[str, int] = None,
106
    datefrom: str = None,
107
    dateto: str = None,
108
    organization: str = None,
109
    tag: str = None,
110
    **kwargs
111
) -> List[Dict]:
112
    """
113
    Search event index with text-based filtering.
114
    
115
    Parameters:
116
    - all: Search across all fields
117
    - attribute: Search in attributes
118
    - email: Search by email addresses
119
    - published: Filter by published status
120
    - hasproposal: Filter events with proposals
121
    - eventid: Specific event ID
122
    - datefrom: Start date
123
    - dateto: End date
124
    - organization: Organization filter
125
    - tag: Tag filter
126
    
127
    Returns:
128
    List of matching events (index format)
129
    """
130
```
131

132
### Specialized Search Functions
133

134
Targeted search functions for specific data types and use cases.
135

136
```python { .api }
137
def search_sightings(
138
    self,
139
    context: str = None,
140
    context_id: Union[str, int] = None,
141
    type_sighting: str = None,
142
    date_from: Union[str, datetime] = None,
143
    date_to: Union[str, datetime] = None,
144
    last: str = None,
145
    org: Union[str, int] = None,
146
    source: str = None,
147
    include_attribute: bool = None,
148
    include_event: bool = None,
149
    **kwargs
150
) -> List[Dict]:
151
    """
152
    Search sighting data.
153
    
154
    Parameters:
155
    - context: Sighting context ('attribute', 'event')
156
    - context_id: ID of context object
157
    - type_sighting: Sighting type (0=sighting, 1=false positive, 2=expiration)
158
    - date_from: Start date for sightings
159
    - date_to: End date for sightings
160
    - last: Time range
161
    - org: Organization filter
162
    - source: Sighting source
163
    - include_attribute: Include attribute data
164
    - include_event: Include event data
165
    
166
    Returns:
167
    List of sighting records
168
    """
169

170
def search_logs(
171
    self,
172
    limit: int = None,
173
    page: int = None,
174
    log_id: Union[int, str] = None,
175
    title: str = None,
176
    created: str = None,
177
    model: str = None,
178
    action: str = None,
179
    user_id: Union[int, str] = None,
180
    change: str = None,
181
    email: str = None,
182
    org: str = None,
183
    description: str = None,
184
    ip: str = None,
185
    **kwargs
186
) -> List[Dict]:
187
    """
188
    Search system logs.
189
    
190
    Parameters:
191
    - limit: Maximum logs to return
192
    - page: Page number
193
    - log_id: Specific log ID
194
    - title: Log title filter
195
    - created: Creation date filter
196
    - model: MISP model filter
197
    - action: Action type filter
198
    - user_id: User ID filter
199
    - change: Change description filter
200
    - email: User email filter
201
    - org: Organization filter
202
    - description: Description filter
203
    - ip: IP address filter
204
    
205
    Returns:
206
    List of log entries
207
    """
208

209
def search_tags(
210
    self,
211
    tagname: str = None,
212
    **kwargs
213
) -> List[Dict]:
214
    """
215
    Search available tags.
216
    
217
    Parameters:
218
    - tagname: Tag name filter (supports wildcards)
219
    
220
    Returns:
221
    List of matching tags
222
    """
223

224
def search_galaxy(
225
    self,
226
    galaxy_name: str = None,
227
    **kwargs
228
) -> List[Dict]:
229
    """
230
    Search galaxy knowledge base.
231
    
232
    Parameters:
233
    - galaxy_name: Galaxy name filter
234
    
235
    Returns:
236
    List of matching galaxies
237
    """
238

239
def search_galaxy_clusters(
240
    self,
241
    galaxy_id: Union[int, str] = None,
242
    cluster_value: str = None,
243
    **kwargs
244
) -> List[Dict]:
245
    """
246
    Search galaxy clusters.
247
    
248
    Parameters:
249
    - galaxy_id: Specific galaxy ID
250
    - cluster_value: Cluster value filter
251
    
252
    Returns:
253
    List of matching galaxy clusters
254
    """
255
```
256

257
### Advanced Search Options
258

259
Advanced search capabilities with complex filters and export options.
260

261
```python { .api }
262
def build_complex_query(
263
    self,
264
    or_parameters: List[Dict] = None,
265
    and_parameters: List[Dict] = None,
266
    not_parameters: List[Dict] = None
267
) -> Dict:
268
    """
269
    Build complex search query with logical operators.
270
    
271
    Parameters:
272
    - or_parameters: OR conditions
273
    - and_parameters: AND conditions  
274
    - not_parameters: NOT conditions
275
    
276
    Returns:
277
    Complex query structure
278
    """
279

280
def get_csv(
281
    self,
282
    eventid: Union[str, int, List] = None,
283
    ignore: bool = None,
284
    tags: Union[str, List[str]] = None,
285
    category: Union[str, List[str]] = None,
286
    type_attribute: Union[str, List[str]] = None,
287
    include_context: bool = True,
288
    **kwargs
289
) -> str:
290
    """
291
    Export search results as CSV.
292
    
293
    Parameters:
294
    - eventid: Event IDs to export
295
    - ignore: Ignore warning list
296
    - tags: Tag filters
297
    - category: Category filters
298
    - type_attribute: Type filters
299
    - include_context: Include contextual data
300
    
301
    Returns:
302
    CSV formatted string
303
    """
304
```
305

306
## Usage Examples
307

308
### Basic Search Operations
309

310
```python
311
from pymisp import PyMISP
312
from datetime import datetime, timedelta
313

314
misp = PyMISP('https://misp.example.com', 'your-api-key')
315

316
# Search for specific IP address
317
ip_results = misp.search(value='192.168.1.100')
318

319
# Search for domain patterns
320
domain_results = misp.search(
321
    value='%.malware.com',
322
    type_attribute='domain'
323
)
324

325
# Search recent events
326
recent_events = misp.search(
327
    controller='events',
328
    last='7d',
329
    published=True
330
)
331
```
332

333
### Advanced Filtering
334

335
```python
336
# Search with multiple filters
337
advanced_results = misp.search(
338
    controller='attributes',
339
    type_attribute=['ip-dst', 'domain', 'url'],
340
    category='Network activity',
341
    tags=['apt', 'malware'],
342
    not_tags=['false-positive'],
343
    org=[1, 2, 3],
344
    to_ids=True,
345
    last='30d'
346
)
347

348
# Search with date range
349
from datetime import datetime, timedelta
350

351
end_date = datetime.now()
352
start_date = end_date - timedelta(days=30)
353

354
date_filtered = misp.search(
355
    date_from=start_date,
356
    date_to=end_date,
357
    published=True
358
)
359
```
360

361
### Text-Based Search
362

363
```python
364
# Search across all fields
365
text_search = misp.search(searchall='APT campaign')
366

367
# Search event info
368
info_search = misp.search(
369
    controller='events',
370
    eventinfo='*malware*'
371
)
372

373
# Search with index
374
index_results = misp.search_index(
375
    all='targeted attack',
376
    published=True,
377
    datefrom='2024-01-01'
378
)
379
```
380

381
### Export & Format Options
382

383
```python
384
# Export as different formats
385
stix_export = misp.search(
386
    eventid=[1, 2, 3],
387
    return_format='stix2'
388
)
389

390
csv_export = misp.search(
391
    tags=['apt'],
392
    return_format='csv',
393
    include_context=True
394
)
395

396
# Get CSV directly
397
csv_data = misp.get_csv(
398
    eventid=[1, 2, 3],
399
    category=['Network activity', 'Payload delivery'],
400
    include_context=True
401
)
402
```
403

404
### Sighting & Log Search
405

406
```python
407
# Search sightings
408
sightings = misp.search_sightings(
409
    context='attribute',
410
    last='7d',
411
    include_attribute=True
412
)
413

414
# Search system logs
415
logs = misp.search_logs(
416
    action='add',
417
    model='Event',
418
    user_id=1,
419
    last='24h'
420
)
421

422
# Search tags
423
matching_tags = misp.search_tags(tagname='apt*')
424
```
425

426
### Complex Query Building
427

428
```python
429
# Build complex OR query
430
complex_query = misp.build_complex_query(
431
    or_parameters=[
432
        {'type': 'ip-dst', 'value': '192.168.1.100'},
433
        {'type': 'domain', 'value': 'malware.com'},
434
        {'type': 'url', 'value': '*evil.com*'}
435
    ],
436
    and_parameters=[
437
        {'tags': 'apt'},
438
        {'published': True}
439
    ],
440
    not_parameters=[
441
        {'tags': 'false-positive'}
442
    ]
443
)
444

445
results = misp.search(**complex_query)
446
```
447

448
### Correlation & Context Search
449

450
```python
451
# Search with correlations
452
correlated_search = misp.search(
453
    value='192.168.1.100',
454
    include_correlations=True,
455
    include_sightings=True
456
)
457

458
# Search with decay scoring
459
decay_search = misp.search(
460
    tags=['apt'],
461
    include_decay_score=True,
462
    score=50,  # Minimum score
463
    exclude_decayed=True
464
)
465

466
# Context-aware search
467
context_search = misp.search(
468
    value='malware.exe',
469
    include_context=True,
470
    include_event_tags=True,
471
    requested_attributes=['md5', 'sha1', 'filename']
472
)
473
```
474

475
## Types
476

477
```python { .api }
478
from typing import Union, List, Dict, Optional, Any
479
from datetime import datetime
480

481
SearchValue = Union[str, int, List[Union[str, int]]]
482
SearchFilter = Dict[str, Any]
483
SearchResults = Union[List[Dict], Dict]
484
ExportFormat = str  # 'json', 'xml', 'csv', 'stix', 'stix2', 'yara', etc.
485
TimeRange = str  # '5d', '2h', '30m', etc.
486
```