0
# Core API Client
1

2
The PyMISP class serves as the main interface for interacting with MISP instances, providing authentication, connection management, and access to all MISP functionality.
3

4
## Capabilities
5

6
### Client Initialization
7

8
Initialize PyMISP client with connection parameters and authentication credentials.
9

10
```python { .api }
11
class PyMISP:
12
    def __init__(
13
        self,
14
        url: str,
15
        key: str,
16
        ssl: bool | str = True,
17
        debug: bool = False,
18
        proxies: MutableMapping[str, str] | None = None,
19
        cert: str | tuple[str, str] | None = None,
20
        auth: AuthBase | None = None,
21
        tool: str = '',
22
        timeout: float | tuple[float, float] | None = None,
23
        http_headers: dict[str, str] | None = None,
24
        https_adapter: requests.adapters.BaseAdapter | None = None,
25
        http_auth_header_name: str = 'Authorization'
26
    ) -> None:
27
        """
28
        Initialize PyMISP client.
29
        
30
        Parameters:
31
        - url: MISP instance URL (required)
32
        - key: API authentication key (required)
33
        - ssl: SSL certificate verification (True/False) or CA bundle path
34
        - debug: Enable debug logging
35
        - proxies: HTTP/HTTPS proxy configuration
36
        - cert: Client certificate for mutual TLS authentication
37
        - auth: Custom authentication handler
38
        - tool: Tool identifier for user agent string
39
        - timeout: Request timeout (seconds) or (connect, read) tuple
40
        - http_headers: Additional HTTP headers
41
        - https_adapter: Custom HTTPS adapter
42
        - http_auth_header_name: Authentication header name
43
        """
44
```
45

46
### Client Properties
47

48
Access client information and MISP instance details.
49

50
```python { .api }
51
@property
52
def version(self) -> dict[str, Any] | list[dict[str, Any]]:
53
    """Get PyMISP library version information."""
54

55
@cached_property
56
def misp_instance_version(self) -> dict[str, Any] | list[dict[str, Any]]:
57
    """Get connected MISP instance version and capabilities."""
58

59
@property
60
def recommended_pymisp_version(self) -> dict[str, Any] | list[dict[str, Any]]:
61
    """Get recommended PyMISP version for this MISP instance."""
62

63
@property
64
def describe_types_local(self) -> dict[str, Any] | list[dict[str, Any]]:
65
    """Get local MISP attribute type descriptions from package."""
66

67
@property
68
def describe_types_remote(self) -> dict[str, Any] | list[dict[str, Any]]:
69
    """Get remote MISP attribute type descriptions from server."""
70

71
@property
72
def pymisp_version_main(self) -> dict[str, Any] | list[dict[str, Any]]:
73
    """Get latest PyMISP version from GitHub main branch."""
74
```
75

76
### Server Configuration
77

78
Manage server settings and system administration.
79

80
```python { .api }
81
def toggle_global_pythonify(self) -> None:
82
    """Toggle global pythonify setting for all responses."""
83

84
def set_server_setting(self, setting: str, value: str | int | bool, force: bool = False) -> dict[str, Any] | list[dict[str, Any]]:
85
    """Set MISP server configuration setting."""
86

87
def get_server_setting(self, setting: str) -> dict[str, Any] | list[dict[str, Any]]:
88
    """Get MISP server configuration setting."""
89

90
def server_settings(self) -> dict[str, Any] | list[dict[str, Any]]:
91
    """Get all server configuration settings."""
92

93
def restart_workers(self) -> dict[str, Any] | list[dict[str, Any]]:
94
    """Restart MISP background worker processes."""
95

96
def db_schema_diagnostic(self) -> dict[str, Any] | list[dict[str, Any]]:
97
    """Get database schema diagnostic information."""
98

99
def update_misp(self) -> dict[str, Any] | list[dict[str, Any]]:
100
    """Trigger MISP instance update process."""
101
```
102

103
### Access Control & Diagnostics
104

105
Manage access control and system diagnostics.
106

107
```python { .api }
108
def remote_acl(self, debug_type: str = 'findMissingFunctionNames') -> dict[str, Any] | list[dict[str, Any]]:
109
    """
110
    Check remote access control list status.
111
    
112
    Parameters:
113
    - debug_type: 'findMissingFunctionNames', 'printAllFunctionNames', or 'printRoleAccess'
114
    """
115
```
116

117

118
## Usage Examples
119

120
### Basic Client Setup
121

122
```python
123
from pymisp import PyMISP
124

125
# Basic initialization
126
misp = PyMISP('https://misp.example.com', 'your-api-key')
127

128
# With additional options
129
misp = PyMISP(
130
    url='https://misp.example.com',
131
    key='your-api-key',
132
    ssl=True,
133
    debug=False,
134
    timeout=30,
135
    proxies={'https': 'proxy.company.com:8080'}
136
)
137
```
138

139
### Version Information
140

141
```python
142
# Get PyMISP version
143
version_info = misp.version
144
print(f"PyMISP Version: {version_info['version']}")
145

146
# Get MISP instance version
147
instance_version = misp.misp_instance_version
148
print(f"MISP Version: {instance_version['version']}")
149

150
# Get recommended PyMISP version
151
recommended = misp.recommended_pymisp_version
152
print(f"Recommended PyMISP: {recommended['version']}")
153
```
154

155
### Server Configuration
156

157
```python
158
# Get supported attribute types
159
types = misp.describe_types_remote
160
print(f"Categories: {list(types['categories'])}")
161
print(f"Attribute types: {list(types['types'].keys())}")
162

163
# Configure server settings
164
misp.set_server_setting('MISP.background_jobs', True)
165
setting_value = misp.get_server_setting('MISP.background_jobs')
166
print(f"Background jobs enabled: {setting_value}")
167

168
# Restart workers
169
restart_result = misp.restart_workers()
170
print(f"Workers restart: {restart_result}")
171
```
172

173
### Error Handling
174

175
```python
176
from pymisp.exceptions import PyMISPError, MISPServerError, NoURL, NoKey
177

178
try:
179
    misp = PyMISP('https://misp.example.com', 'invalid-key')
180
    events = misp.events()
181
except NoURL:
182
    print("No MISP URL provided")
183
except NoKey:
184
    print("No API key provided")
185
except MISPServerError as e:
186
    print(f"Server error: {e}")
187
except PyMISPError as e:
188
    print(f"PyMISP error: {e}")
189
```
190

191
## Types
192

193
```python { .api }
194
from typing import Any, MutableMapping, TypeVar
195
from requests.auth import AuthBase
196
from requests.adapters import BaseAdapter
197

198
# Type aliases used in PyMISP
199
SearchType = TypeVar('SearchType', str, int)
200
SearchParameterTypes = TypeVar('SearchParameterTypes', str, list[str | int], dict[str, str | int])
201
ToIDSType = TypeVar('ToIDSType', str, int, bool)
202
```