idnits 2.17.1 draft-dulaunoy-misp-object-template-format-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There are 4 instances of too long lines in the document, the longest one being 58 characters in excess of 72. ** The abstract seems to contain references ([MISP-O]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 15, 2018) is 2020 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) Summary: 5 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Dulaunoy 3 Internet-Draft A. Iklody 4 Intended status: Informational CIRCL 5 Expires: April 18, 2019 October 15, 2018 7 MISP object template format 8 draft-dulaunoy-misp-object-template-format-02 10 Abstract 12 This document describes the MISP object template format which 13 describes a simple JSON format to represent the various templates 14 used to construct MISP objects. A public directory of common 15 vocabularies MISP object templates [MISP-O] is available and relies 16 on the MISP object reference format. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at https://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on April 18, 2019. 35 Copyright Notice 37 Copyright (c) 2018 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (https://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 2 54 2. Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2.1.1. Object Template . . . . . . . . . . . . . . . . . . . 3 57 2.1.2. attributes . . . . . . . . . . . . . . . . . . . . . 4 58 2.1.3. Sample Object Template object . . . . . . . . . . . . 6 59 2.1.4. Object Relationships . . . . . . . . . . . . . . . . 9 60 3. Directory . . . . . . . . . . . . . . . . . . . . . . . . . . 10 61 4. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 62 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 63 5.1. Normative References . . . . . . . . . . . . . . . . . . 10 64 5.2. Informative References . . . . . . . . . . . . . . . . . 10 65 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 67 1. Introduction 69 Due to the increased maturity of threat information sharing, the need 70 arose for more complex and exhaustive data-points to be shared across 71 the various sharing communities. MISP's information sharing in 72 general relied on a flat structure of attributes contained within an 73 event, where attributes served as atomic secluded data-points with 74 some commonalities as defined by the encapsulating event. However, 75 this flat structure restricted the use of more diverse and complex 76 data-points described by a list of atomic values, a problem solved by 77 the MISP object structure. 79 MISP objects combine a list of attributes to represent a singular 80 object with various facets. In order to bootstrap the object 81 creation process and to maintain uniformity among objects describing 82 similar data-points, the MISP object template format serves as a 83 reusable and share-able blueprint format. 85 MISP object templates also include a vocabulary to describe the 86 various inter object and object to attribute relationships and are 87 leveraged by MISP object references. 89 1.1. Conventions and Terminology 91 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 92 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 93 document are to be interpreted as described in RFC 2119 [RFC2119]. 95 2. Format 97 MISP object templates are composed of the MISP object template (MUST) 98 structure itself and a list of MISP object template elements (SHOULD) 99 describing the list of possible attributes belonging to the resulting 100 object, along with their context and settings. 102 MISP object templates themselves consist of a name (MUST), a meta- 103 category (MUST) and a description (SHOULD). They are identified by a 104 uuid (MUST) and a version (MUST). For any updates or transfer of the 105 same object reference. UUID version 4 is RECOMMENDED when assigning 106 it to a new object reference. The list of requirements when it comes 107 to the contained MISP object template elements is defined in the 108 requirements field (OPTIONAL). 110 MISP object template elements consist of an object_relation (MUST), a 111 type (MUST), an object_template_id (SHOULD), a ui_priority (SHOULD), 112 a list of categories (MAY), a list of sane_default values (MAY) or a 113 values_list (MAY). 115 2.1. Overview 117 The MISP object template format uses the JSON [RFC4627] format. Each 118 template is represented as a JSON object with meta information 119 including the following fields: uuid, requiredOneOf, description, 120 version, meta-category, name. 122 2.1.1. Object Template 124 2.1.1.1. uuid 126 uuid represents the Universally Unique IDentifier (UUID) [RFC4122] of 127 the object template. The uuid MUST be preserved for to keep 128 consistency of the templates across instances. UUID version 4 is 129 RECOMMENDED when assigning it to a new object template. 131 uuid is represented as a JSON string. uuid MUST be present. 133 2.1.1.2. requiredOneOf 135 requiredOneOf is represented as a JSON list and contains a list of 136 attribute relationships of which one must be present in the object to 137 be created based on the given template. The requiredOneOf field MAY 138 be present. 140 2.1.1.3. required 142 required is represented as a JSON list and contains a list of 143 attribute relationships of which all must be present in the object to 144 be created based on the given template. The required field MAY be 145 present. 147 2.1.1.4. description 149 description is represented as a JSON string and contains the assigned 150 meaning given to objects created using this template. The 151 description field MUST be present. 153 2.1.1.5. version 155 version represents a numeric incrementing version of the object 156 template. It is used to associate the object to the correct version 157 of the template and together with the uuid field forms an association 158 to the correct template type and version. 160 version is represented as a JSON string. version MUST be present. 162 2.1.1.6. meta-category 164 meta-category represents the sub-category of objects that the given 165 object template belongs to. meta-categories are not tied to a fixed 166 list of options but can be created on the fly. 168 meta-category is represented as a JSON string. meta-category MUST be 169 present. 171 2.1.1.7. name 173 name represents the human-readable name of the objects created using 174 the given template, describing the intent of the object package. 176 name is represented as a JSON string. name MUST be present 178 2.1.2. attributes 180 attributes is represented as a JSON list and contains a list of 181 template elements used as a template for creating the individual 182 attributes within the object that is to be created with the object. 184 attributes is represented as a JSON list. attributes MUST be present. 186 2.1.2.1. description 188 description is represented as a JSON string and contains the 189 description of the given attribute in the context of the object with 190 the given relationship. The description field MUST be present. 192 2.1.2.2. ui-priority 194 ui-priority is represented by a numeric values in JSON string format 195 and is meant to provide a priority for the given element in the 196 object template visualisation. The ui-priority MAY be present. 198 2.1.2.3. misp-attribute 200 misp-attribute is represented by a JSON string or a JSON object with 201 a list of values. The value(s) are taken from the pool of types 202 defined by the MISP core format's Attribute Object's type list. type 203 can contain a JSON object with a list of suggested value alternatives 204 encapsulated in a list within a sane_default key or a list of 205 enforced value alternatives encapsulated in a list_values key. 207 The misp-attribute field MUST be present. 209 2.1.2.4. disable_correlation 211 disable_correlation is represented by a JSON boolean. The 212 disable_correlation field flags the attribute(s) created by the given 213 object template element to be marked as non correlating. 215 The misp-attribute field MAY be present. 217 2.1.2.5. categories 219 categories is represented by a JSON list containing one or several 220 valid options from the list of verbs valid for the category field in 221 the Attribute object within the MISP core format. 223 The categories field MAY be present. 225 2.1.2.6. multiple 227 multiple is represented by a JSON boolean value. It marks the MISP 228 object template element as a multiple input field, allowing for 229 several attributes to be created by the element within the same 230 object. 232 The multiple field MAY be present. 234 2.1.2.7. sane_default 236 sane_default is represented by a JSON list containing one or several 237 recommended/sane values for an attribute. sane_default is mutually 238 exclusive with values_list. 240 The sane_default field MAY be present. 242 2.1.2.8. values_list 244 values_list is represented by a JSON List containing one or several 245 of fixed values for an attribute. values_list is mutually exclusive 246 with sane_default. 248 The value_list field MAY be present. 250 2.1.3. Sample Object Template object 252 The MISP object template directory is publicly available [MISP-O] in 253 a git repository and contains more than 60 object templates. As 254 illustration, two sample objects templates are included. 256 2.1.3.1. credit-card object template 257 { 258 "requiredOneOf": [ 259 "cc-number" 260 ], 261 "attributes": { 262 "version": { 263 "description": "Version of the card.", 264 "ui-priority": 0, 265 "misp-attribute": "text" 266 }, 267 "comment": { 268 "description": "A description of the card.", 269 "ui-priority": 0, 270 "misp-attribute": "comment" 271 }, 272 "card-security-code": { 273 "description": "Card security code (CSC, CVD, CVV, CVC and SPC) as embossed or printed on the card.", 274 "ui-priority": 0, 275 "misp-attribute": "text" 276 }, 277 "name": { 278 "description": "Name of the card owner.", 279 "ui-priority": 0, 280 "misp-attribute": "text" 281 }, 282 "issued": { 283 "description": "Initial date of validity or issued date.", 284 "ui-priority": 0, 285 "misp-attribute": "datetime" 286 }, 287 "expiration": { 288 "description": "Maximum date of validity", 289 "ui-priority": 0, 290 "misp-attribute": "datetime" 291 }, 292 "cc-number": { 293 "description": "credit-card number as encoded on the card.", 294 "ui-priority": 0, 295 "misp-attribute": "cc-number" 296 } 297 }, 298 "version": 2, 299 "description": "A payment card like credit card, debit card or any similar cards which can be used for financial transactions.", 300 "meta-category": "financial", 301 "uuid": "2b9c57aa-daba-4330-a738-56f18743b0c7", 302 "name": "credit-card" 303 } 304 2.1.3.2. credential object template 306 { 307 "requiredOneOf": [ 308 "password" 309 ], 310 "attributes": { 311 "text": { 312 "description": "A description of the credential(s)", 313 "disable_correlation": true, 314 "ui-priority": 1, 315 "misp-attribute": "text" 316 }, 317 "username": { 318 "description": "Username related to the password(s)", 319 "ui-priority": 1, 320 "misp-attribute": "text" 321 }, 322 "password": { 323 "description": "Password", 324 "multiple": true, 325 "ui-priority": 1, 326 "misp-attribute": "text" 327 }, 328 "type": { 329 "description": "Type of password(s)", 330 "ui-priority": 1, 331 "misp-attribute": "text", 332 "values_list": [ 333 "password", 334 "api-key", 335 "encryption-key", 336 "unknown" 337 ] 338 }, 339 "origin": { 340 "description": "Origin of the credential(s)", 341 "ui-priority": 1, 342 "misp-attribute": "text", 343 "sane_default": [ 344 "bruteforce-scanning", 345 "malware-analysis", 346 "memory-analysis", 347 "network-analysis", 348 "leak", 349 "unknown" 350 ] 351 }, 352 "format": { 353 "description": "Format of the password(s)", 354 "ui-priority": 1, 355 "misp-attribute": "text", 356 "values_list": [ 357 "clear-text", 358 "hashed", 359 "encrypted", 360 "unknown" 361 ] 362 }, 363 "notification": { 364 "description": "Mention of any notification(s) towards the potential owner(s) of the credential(s)", 365 "ui-priority": 1, 366 "misp-attribute": "text", 367 "multiple": true, 368 "values_list": [ 369 "victim-notified", 370 "service-notified", 371 "none" 372 ] 373 } 374 }, 375 "version": 2, 376 "description": "Credential describes one or more credential(s) including password(s), api key(s) or decryption key(s).", 377 "meta-category": "misc", 378 "uuid": "a27e98c9-9b0e-414c-8076-d201e039ca09", 379 "name": "credential" 380 } 382 2.1.4. Object Relationships 384 2.1.4.1. name 386 name represents the human-readable relationship type which can be 387 used when creating MISP object relations. 389 name is represented as a JSON string. name MUST be present. 391 2.1.4.2. description 393 description is represented as a JSON string and contains the 394 description of the object relationship type. The description field 395 MUST be present. 397 2.1.4.3. format 399 format is represented by a JSON list containing a list of formats 400 that the relationship type is valid for and can be mapped to. The 401 format field MUST be present. 403 3. Directory 405 The MISP object template directory is publicly available [MISP-O] in 406 a git repository. The repository contains an objects directory, 407 which contains a directory per object type, containing a file named 408 definition.json which contains the definition of the object template 409 in the above described format. 411 A relationships directory is also included, containing a 412 definition.json file which contains a list of MISP object relation 413 definitions. There are more than 90 existing templates object 414 documented in [MISP-O-DOC]. 416 4. Acknowledgements 418 The authors wish to thank all the MISP community who are supporting 419 the creation of open standards in threat intelligence sharing. 421 5. References 423 5.1. Normative References 425 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 426 Requirement Levels", BCP 14, RFC 2119, 427 DOI 10.17487/RFC2119, March 1997, 428 . 430 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 431 Unique IDentifier (UUID) URN Namespace", RFC 4122, 432 DOI 10.17487/RFC4122, July 2005, 433 . 435 [RFC4627] Crockford, D., "The application/json Media Type for 436 JavaScript Object Notation (JSON)", RFC 4627, 437 DOI 10.17487/RFC4627, July 2006, 438 . 440 5.2. Informative References 442 [MISP-O] MISP, "MISP Objects - shared and common object templates", 443 . 445 [MISP-O-DOC] 446 "MISP objects directory", 2018, 447 . 449 Authors' Addresses 451 Alexandre Dulaunoy 452 Computer Incident Response Center Luxembourg 453 16, bd d'Avranches 454 Luxembourg L-1611 455 Luxembourg 457 Phone: +352 247 88444 458 Email: alexandre.dulaunoy@circl.lu 460 Andras Iklody 461 Computer Incident Response Center Luxembourg 462 16, bd d'Avranches 463 Luxembourg L-1611 464 Luxembourg 466 Phone: +352 247 88444 467 Email: andras.iklody@circl.lu