0
# STIX Cyber Observable Objects (SCOs)
1

2
STIX Cyber Observable Objects represent observable cyber artifacts such as files, network addresses, processes, registry keys, and other technical indicators that can be observed in cyber operations. These objects capture the technical details of cyber activities and form the foundation for technical threat intelligence.
3

4
## Capabilities
5

6
### File System Objects
7

8
Objects representing files, directories, and file system artifacts.
9

10
```python { .api }
11
class File:
12
    """
13
    File objects represent properties of files.
14
    
15
    Optional Properties:
16
    - hashes (dict): Cryptographic hashes of the file
17
    - size (int): Size of the file in bytes
18
    - name (str): Name of the file
19
    - name_enc (str): Character encoding of the name
20
    - magic_number_hex (str): Magic number in hexadecimal
21
    - mime_type (str): MIME type of the file
22
    - ctime (timestamp): Creation time
23
    - mtime (timestamp): Modification time
24
    - atime (timestamp): Access time
25
    - parent_directory_ref (str): Reference to parent directory
26
    - contains_refs (list): References to contained objects
27
    - content_ref (str): Reference to file content artifact
28
    - extensions (dict): File extensions
29
    """
30

31
class Directory:
32
    """
33
    Directory objects represent properties of file system directories.
34
    
35
    Required Properties:
36
    - path (str): Path of the directory
37
    
38
    Optional Properties:
39
    - path_enc (str): Character encoding of the path
40
    - ctime (timestamp): Creation time
41
    - mtime (timestamp): Modification time
42
    - atime (timestamp): Access time
43
    - contains_refs (list): References to contained objects
44
    """
45

46
class Artifact:
47
    """
48
    Artifact objects represent collections of bytes or payloads.
49
    
50
    Optional Properties:
51
    - mime_type (str): MIME type of the artifact
52
    - payload_bin (str): Base64-encoded payload
53
    - url (str): URL to download the payload
54
    - hashes (dict): Cryptographic hashes
55
    - encryption_algorithm (str): Encryption algorithm used
56
    - decryption_key (str): Key for decryption
57
    """
58
```
59

60
Usage examples:
61

62
```python
63
from stix2 import File, Directory, Artifact
64

65
# Create file object
66
file_obj = File(
67
    hashes={
68
        "MD5": "d41d8cd98f00b204e9800998ecf8427e",
69
        "SHA-1": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
70
        "SHA-256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
71
    },
72
    size=0,
73
    name="empty.txt",
74
    mime_type="text/plain"
75
)
76

77
# Create directory object
78
directory = Directory(
79
    path="/home/user/documents",
80
    ctime="2021-04-23T10:30:00.000Z",
81
    mtime="2021-04-23T11:15:00.000Z"
82
)
83

84
# Create artifact object
85
artifact = Artifact(
86
    mime_type="application/pdf",
87
    hashes={
88
        "SHA-256": "b5b2bc5a6e4c7e5a8c6b9a0f3e2d1c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4e3d2c1"
89
    },
90
    url="https://example.com/document.pdf"
91
)
92
```
93

94
### Network Objects
95

96
Objects representing network addresses, traffic, and communications.
97

98
```python { .api }
99
class IPv4Address:
100
    """
101
    IPv4 address objects represent IPv4 addresses.
102
    
103
    Required Properties:
104
    - value (str): IPv4 address value
105
    
106
    Optional Properties:
107
    - resolves_to_refs (list): References to resolved MAC addresses
108
    - belongs_to_refs (list): References to AS objects
109
    """
110

111
class IPv6Address:
112
    """
113
    IPv6 address objects represent IPv6 addresses.
114
    
115
    Required Properties:
116
    - value (str): IPv6 address value
117
    
118
    Optional Properties:
119
    - resolves_to_refs (list): References to resolved MAC addresses
120
    - belongs_to_refs (list): References to AS objects
121
    """
122

123
class DomainName:
124
    """
125
    Domain name objects represent domain names.
126
    
127
    Required Properties:
128
    - value (str): Domain name value
129
    
130
    Optional Properties:
131
    - resolves_to_refs (list): References to resolved IP addresses
132
    """
133

134
class URL:
135
    """
136
    URL objects represent Uniform Resource Locators.
137
    
138
    Required Properties:
139
    - value (str): URL value
140
    """
141

142
class MACAddress:
143
    """
144
    MAC address objects represent Media Access Control addresses.
145
    
146
    Required Properties:
147
    - value (str): MAC address value
148
    """
149

150
class NetworkTraffic:
151
    """
152
    Network traffic objects represent network connections and traffic.
153
    
154
    Required Properties:
155
    - protocols (list): Network protocols used
156
    
157
    Optional Properties:
158
    - start (timestamp): Start time of traffic
159
    - end (timestamp): End time of traffic
160
    - is_active (bool): Whether traffic is active
161
    - src_ref (str): Reference to source address
162
    - dst_ref (str): Reference to destination address
163
    - src_port (int): Source port number
164
    - dst_port (int): Destination port number
165
    - src_byte_count (int): Source byte count
166
    - dst_byte_count (int): Destination byte count
167
    - src_packets (int): Source packet count
168
    - dst_packets (int): Destination packet count
169
    - ipfix (dict): IPFIX data
170
    - src_payload_ref (str): Reference to source payload
171
    - dst_payload_ref (str): Reference to destination payload
172
    - encapsulates_refs (list): References to encapsulated traffic
173
    - encapsulated_by_ref (str): Reference to encapsulating traffic
174
    - extensions (dict): Network traffic extensions
175
    """
176

177
class AutonomousSystem:
178
    """
179
    Autonomous System objects represent autonomous systems.
180
    
181
    Required Properties:
182
    - number (int): AS number
183
    
184
    Optional Properties:
185
    - name (str): AS name
186
    - rir (str): Regional Internet Registry
187
    """
188
```
189

190
Usage examples:
191

192
```python
193
from stix2 import IPv4Address, DomainName, NetworkTraffic, URL
194

195
# Create IP address
196
ip_addr = IPv4Address(value="192.168.1.1")
197

198
# Create domain name that resolves to IP
199
domain = DomainName(
200
    value="example.com",
201
    resolves_to_refs=[ip_addr.id]
202
)
203

204
# Create network traffic
205
traffic = NetworkTraffic(
206
    protocols=["tcp", "http"],
207
    src_ref=ip_addr.id,
208
    src_port=54321,
209
    dst_port=80,
210
    start="2021-04-23T10:30:00.000Z"
211
)
212

213
# Create URL
214
url = URL(value="https://example.com/malicious-page")
215
```
216

217
### Email Objects
218

219
Objects representing email addresses and email messages.
220

221
```python { .api }
222
class EmailAddress:
223
    """
224
    Email address objects represent email addresses.
225
    
226
    Required Properties:
227
    - value (str): Email address value
228
    
229
    Optional Properties:
230
    - display_name (str): Display name associated with address
231
    - belongs_to_ref (str): Reference to user account
232
    """
233

234
class EmailMessage:
235
    """
236
    Email message objects represent email messages.
237
    
238
    Optional Properties:
239
    - is_multipart (bool): Whether message has multiple parts
240
    - date (timestamp): Date header value
241
    - content_type (str): Content-Type header value
242
    - from_ref (str): Reference to sender email address
243
    - sender_ref (str): Reference to Sender header address
244
    - to_refs (list): References to To header addresses
245
    - cc_refs (list): References to CC header addresses
246
    - bcc_refs (list): References to BCC header addresses
247
    - message_id (str): Message-ID header value
248
    - subject (str): Subject header value
249
    - received_lines (list): Received header lines
250
    - additional_header_fields (dict): Additional header fields
251
    - body (str): Email body content
252
    - body_multipart (list): Multipart body components
253
    - raw_email_ref (str): Reference to raw email artifact
254
    """
255

256
class EmailMIMEComponent:
257
    """
258
    Email MIME component objects represent MIME parts of email messages.
259
    
260
    Optional Properties:
261
    - body (str): Body content of MIME part
262
    - body_raw_ref (str): Reference to raw body artifact
263
    - content_type (str): Content-Type of MIME part
264
    - content_disposition (str): Content-Disposition header
265
    """
266
```
267

268
Usage examples:
269

270
```python
271
from stix2 import EmailAddress, EmailMessage
272

273
# Create email address
274
sender = EmailAddress(
275
    value="attacker@malicious.com",
276
    display_name="Legitimate Company"
277
)
278

279
recipient = EmailAddress(value="victim@company.com")
280

281
# Create email message
282
email = EmailMessage(
283
    from_ref=sender.id,
284
    to_refs=[recipient.id],
285
    subject="Urgent: Account Verification Required",
286
    date="2021-04-23T10:30:00.000Z",
287
    body="Click the link below to verify your account...",
288
    additional_header_fields={
289
        "X-Mailer": "Malicious Mailer 1.0"
290
    }
291
)
292
```
293

294
### Process and Software Objects
295

296
Objects representing running processes and installed software.
297

298
```python { .api }
299
class Process:
300
    """
301
    Process objects represent running processes.
302
    
303
    Optional Properties:
304
    - is_hidden (bool): Whether process is hidden
305
    - pid (int): Process identifier
306
    - name (str): Process name
307
    - created_time (timestamp): Process creation time
308
    - cwd (str): Current working directory
309
    - command_line (str): Command line used to launch
310
    - environment_variables (dict): Environment variables
311
    - opened_connection_refs (list): References to network connections
312
    - creator_user_ref (str): Reference to creator user account
313
    - image_ref (str): Reference to process image file
314
    - parent_ref (str): Reference to parent process
315
    - child_refs (list): References to child processes
316
    - extensions (dict): Process extensions
317
    """
318

319
class Software:
320
    """
321
    Software objects represent software applications.
322
    
323
    Required Properties:
324
    - name (str): Software name
325
    
326
    Optional Properties:
327
    - cpe (str): Common Platform Enumeration identifier
328
    - swid (str): Software Identification tag
329
    - languages (list): Programming languages used
330
    - vendor (str): Software vendor
331
    - version (str): Software version
332
    """
333

334
class UserAccount:
335
    """
336
    User account objects represent user accounts.
337
    
338
    Required Properties:
339
    - user_id (str): User identifier
340
    
341
    Optional Properties:
342
    - credential (str): Account credential
343
    - account_login (str): Account login name
344
    - account_type (str): Type of account
345
    - display_name (str): Display name
346
    - is_service_account (bool): Whether it's a service account
347
    - is_privileged (bool): Whether account is privileged
348
    - can_escalate_privs (bool): Whether can escalate privileges
349
    - is_disabled (bool): Whether account is disabled
350
    - account_created (timestamp): Account creation time
351
    - account_expires (timestamp): Account expiration time
352
    - credential_last_changed (timestamp): Last credential change
353
    - account_first_login (timestamp): First login time
354
    - account_last_login (timestamp): Last login time
355
    - extensions (dict): User account extensions
356
    """
357
```
358

359
Usage examples:
360

361
```python
362
from stix2 import Process, Software, UserAccount
363

364
# Create process
365
process = Process(
366
    pid=1234,
367
    name="malware.exe",
368
    command_line="malware.exe -hidden -connect 192.168.1.100",
369
    created_time="2021-04-23T10:30:00.000Z",
370
    is_hidden=True
371
)
372

373
# Create software
374
software = Software(
375
    name="Microsoft Office",
376
    vendor="Microsoft Corporation",
377
    version="2019",
378
    cpe="cpe:2.3:a:microsoft:office:2019:*:*:*:*:*:*:*"
379
)
380

381
# Create user account
382
user_account = UserAccount(
383
    user_id="john.doe",
384
    account_login="jdoe",
385
    display_name="John Doe",
386
    is_privileged=False,
387
    account_type="windows-local"
388
)
389
```
390

391
### Windows-Specific Objects
392

393
Objects specific to Windows operating systems.
394

395
```python { .api }
396
class WindowsRegistryKey:
397
    """
398
    Windows registry key objects represent Windows registry keys.
399
    
400
    Required Properties:
401
    - key (str): Registry key name
402
    
403
    Optional Properties:
404
    - values (list): Registry key values
405
    - modified_time (timestamp): Last modification time
406
    - creator_user_ref (str): Reference to creator user
407
    - number_of_subkeys (int): Number of subkeys
408
    """
409

410
class WindowsRegistryValueType:
411
    """
412
    Windows registry value type objects represent registry value types.
413
    
414
    Required Properties:
415
    - name (str): Value name
416
    - data (str): Value data
417
    
418
    Optional Properties:
419
    - data_type (str): Data type (REG_SZ, REG_DWORD, etc.)
420
    """
421

422
class Mutex:
423
    """
424
    Mutex objects represent mutual exclusion objects.
425
    
426
    Required Properties:
427
    - name (str): Mutex name
428
    """
429
```
430

431
### X.509 Certificates
432

433
Objects representing X.509 digital certificates.
434

435
```python { .api }
436
class X509Certificate:
437
    """
438
    X.509 certificate objects represent X.509 digital certificates.
439
    
440
    Optional Properties:
441
    - is_self_signed (bool): Whether certificate is self-signed
442
    - hashes (dict): Cryptographic hashes of certificate
443
    - version (str): Certificate version
444
    - serial_number (str): Certificate serial number
445
    - signature_algorithm (str): Signature algorithm
446
    - issuer (str): Certificate issuer
447
    - validity_not_before (timestamp): Validity start time
448
    - validity_not_after (timestamp): Validity end time
449
    - subject (str): Certificate subject
450
    - subject_public_key_algorithm (str): Subject public key algorithm
451
    - subject_public_key_modulus (str): Subject public key modulus
452
    - subject_public_key_exponent (int): Subject public key exponent
453
    - x509_v3_extensions (dict): X.509 v3 extensions
454
    """
455

456
class X509V3ExtensionsType:
457
    """
458
    X.509 v3 extensions type for certificates.
459
    
460
    Optional Properties:
461
    - basic_constraints (str): Basic constraints extension
462
    - name_constraints (str): Name constraints extension
463
    - policy_constraints (str): Policy constraints extension
464
    - key_usage (str): Key usage extension
465
    - extended_key_usage (str): Extended key usage extension
466
    - subject_key_identifier (str): Subject key identifier
467
    - authority_key_identifier (str): Authority key identifier
468
    - subject_alternative_name (str): Subject alternative name
469
    - issuer_alternative_name (str): Issuer alternative name
470
    - subject_directory_attributes (str): Subject directory attributes
471
    - crl_distribution_points (str): CRL distribution points
472
    - inhibit_any_policy (int): Inhibit any policy
473
    - private_key_usage_period_not_before (timestamp): Private key usage start
474
    - private_key_usage_period_not_after (timestamp): Private key usage end
475
    - certificate_policies (str): Certificate policies
476
    - policy_mappings (str): Policy mappings
477
    """
478
```
479

480
## Extensions
481

482
STIX Cyber Observable Objects support extensions for additional properties:
483

484
```python
485
from stix2 import File, NTFSExt, WindowsPEBinaryExt
486

487
# File with NTFS extension
488
file_with_ntfs = File(
489
    name="system.exe",
490
    hashes={"MD5": "abc123"},
491
    extensions={
492
        "ntfs-ext": NTFSExt(
493
            alternate_data_streams=[
494
                {
495
                    "name": "Zone.Identifier",
496
                    "size": 26
497
                }
498
            ]
499
        )
500
    }
501
)
502

503
# File with Windows PE extension
504
pe_file = File(
505
    name="malware.exe", 
506
    hashes={"SHA-256": "def456"},
507
    extensions={
508
        "windows-pebinary-ext": WindowsPEBinaryExt(
509
            pe_type="exe",
510
            machine_hex="014c",
511
            number_of_sections=3
512
        )
513
    }
514
)
515
```
516

517
## Custom Observable Objects
518

519
Create custom observable objects for specific needs:
520

521
```python
522
from stix2 import CustomObservable
523
from stix2.properties import StringProperty, IntegerProperty
524

525
# Define custom observable
526
@CustomObservable('x-custom-log-entry', [
527
    ('log_level', StringProperty(required=True)),
528
    ('message', StringProperty(required=True)),
529
    ('source_ip', StringProperty()),
530
    ('event_count', IntegerProperty()),
531
])
532
class CustomLogEntry:
533
    pass
534

535
# Create instance
536
log_entry = CustomLogEntry(
537
    log_level="ERROR",
538
    message="Authentication failed",
539
    source_ip="192.168.1.100",
540
    event_count=5
541
)
542
```