idnits 2.17.1 draft-dulaunoy-misp-object-template-format-01.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 (April 10, 2018) is 2207 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: October 12, 2018 April 10, 2018 7 MISP object template format 8 draft-dulaunoy-misp-object-template-format-01 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 October 12, 2018. 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). The list of requirements when it 105 comes to the contained MISP object template elements is defined in 106 the requirements field (OPTIONAL). 108 MISP object template elements consist of an object_relation (MUST) a 109 type (MUST) an object_template_id (SHOULD) a ui_priority (SHOULD) a 110 list of categories (MAY), a list of sane_default values (MAY) or a 111 values_list (MAY). 113 2.1. Overview 115 The MISP object template format uses the JSON [RFC4627] format. Each 116 template is represented as a JSON object with meta information 117 including the following fields: uuid, requiredOneOf, description, 118 version, meta-category, name. 120 2.1.1. Object Template 122 2.1.1.1. uuid 124 uuid represents the Universally Unique IDentifier (UUID) [RFC4122] of 125 the object template. The uuid MUST be preserved for to keep 126 consistency of the templates across instances. UUID version 4 is 127 RECOMMENDED when assigning it to a new object template. 129 uuid is represented as a JSON string. uuid MUST be present. 131 2.1.1.2. requiredOneOf 133 requiredOneOf is represented as a JSON list and contains a list of 134 attribute relationships of which one must be present in the object to 135 be created based on the given template. The requiredOneOf field MAY 136 be present. 138 2.1.1.3. required 140 required is represented as a JSON list and contains a list of 141 attribute relationships of which all must be present in the object to 142 be created based on the given template. The required field MAY be 143 present. 145 2.1.1.4. description 147 description is represented as a JSON string and contains the assigned 148 meaning given to objects created using this template. The 149 description field MUST be present. 151 2.1.1.5. version 153 version represents a numeric incrementing version of the object 154 template. It is used to associate the object to the correct version 155 of the template and together with the uuid field forms an association 156 to the correct template type and version. 158 version is represented as a JSON string. version MUST be present. 160 2.1.1.6. meta-category 162 meta-category represents the sub-category of objects that the given 163 object template belongs to. meta-categories are not tied to a fixed 164 list of options but can be created on the fly. 166 meta-category is represented as a JSON string. meta-category MUST be 167 present 169 2.1.1.7. name 171 name represents the human-readable name of the objects created using 172 the given template, describing the intent of the object package. 174 name is represented as a JSON string. name MUST be present 176 2.1.2. attributes 178 attributes is represented as a JSON list and contains a list of 179 template elements used as a template for creating the individual 180 attributes within the object that is to be created with the object. 182 attributes is represented as a JSON list. attributes MUST be present. 184 2.1.2.1. description 186 description is represented as a JSON string and contains the 187 description of the given attribute in the context of the object with 188 the given relationship. The description field MUST be present. 190 2.1.2.2. ui-priority 192 ui-priority is represented by a numeric values in JSON string format 193 and is meant to provide a priority for the given element in the 194 object template visualisation. The ui-priority MAY be present. 196 2.1.2.3. misp-attribute 198 misp-attribute is represented by a JSON string or a JSON object with 199 a list of values. The value(s) are taken from the pool of types 200 defined by the MISP core format's Attribute Object's type list. type 201 can contain a JSON object with a list of suggested value alternatives 202 encapsulated in a list within a sane_default key or a list of 203 enforced value alternatives encapsulated in a list_values key. 205 The misp-attribute field MUST be present. 207 2.1.2.4. disable_correlation 209 disable_correlation is represented by a JSON boolean. The 210 disable_correlation field flags the attribute(s) created by the given 211 object template element to be marked as non correlating. 213 The misp-attribute field MAY be present. 215 2.1.2.5. categories 217 categories is represented by a JSON list containing one or several 218 valid options from the list of verbs valid for the category field in 219 the Attribute object within the MISP core format. 221 The categories field MAY be present. 223 2.1.2.6. multiple 225 multiple is represented by a JSON boolean value. It marks the MISP 226 object template element as a multiple input field, allowing for 227 several attributes to be created by the element within the same 228 object. 230 The multiple field MAY be present. 232 2.1.2.7. sane_default 234 sane_default is represented by a JSON list containing one or several 235 recommended/sane values for an attribute. sane_default is mutually 236 exclusive with values_list. 238 The sane_default field MAY be present. 240 2.1.2.8. values_list 242 values_list is represented by a JSON List containing one or several 243 of fixed values for an attribute. values_list is mutually exclusive 244 with sane_default. 246 The value_list field MAY be present. 248 2.1.3. Sample Object Template object 250 The MISP object template directory is publicly available [MISP-O] in 251 a git repository and contains more than 60 object templates. As 252 illustration, two sample objects templates are included. 254 2.1.3.1. credit-card object template 255 { 256 "requiredOneOf": [ 257 "cc-number" 258 ], 259 "attributes": { 260 "version": { 261 "description": "Version of the card.", 262 "ui-priority": 0, 263 "misp-attribute": "text" 264 }, 265 "comment": { 266 "description": "A description of the card.", 267 "ui-priority": 0, 268 "misp-attribute": "comment" 269 }, 270 "card-security-code": { 271 "description": "Card security code (CSC, CVD, CVV, CVC and SPC) as embossed or printed on the card.", 272 "ui-priority": 0, 273 "misp-attribute": "text" 274 }, 275 "name": { 276 "description": "Name of the card owner.", 277 "ui-priority": 0, 278 "misp-attribute": "text" 279 }, 280 "issued": { 281 "description": "Initial date of validity or issued date.", 282 "ui-priority": 0, 283 "misp-attribute": "datetime" 284 }, 285 "expiration": { 286 "description": "Maximum date of validity", 287 "ui-priority": 0, 288 "misp-attribute": "datetime" 289 }, 290 "cc-number": { 291 "description": "credit-card number as encoded on the card.", 292 "ui-priority": 0, 293 "misp-attribute": "cc-number" 294 } 295 }, 296 "version": 2, 297 "description": "A payment card like credit card, debit card or any similar cards which can be used for financial transactions.", 298 "meta-category": "financial", 299 "uuid": "2b9c57aa-daba-4330-a738-56f18743b0c7", 300 "name": "credit-card" 301 } 302 2.1.3.2. credential object template 304 { 305 "requiredOneOf": [ 306 "password" 307 ], 308 "attributes": { 309 "text": { 310 "description": "A description of the credential(s)", 311 "disable_correlation": true, 312 "ui-priority": 1, 313 "misp-attribute": "text" 314 }, 315 "username": { 316 "description": "Username related to the password(s)", 317 "ui-priority": 1, 318 "misp-attribute": "text" 319 }, 320 "password": { 321 "description": "Password", 322 "multiple": true, 323 "ui-priority": 1, 324 "misp-attribute": "text" 325 }, 326 "type": { 327 "description": "Type of password(s)", 328 "ui-priority": 1, 329 "misp-attribute": "text", 330 "values_list": [ 331 "password", 332 "api-key", 333 "encryption-key", 334 "unknown" 335 ] 336 }, 337 "origin": { 338 "description": "Origin of the credential(s)", 339 "ui-priority": 1, 340 "misp-attribute": "text", 341 "sane_default": [ 342 "bruteforce-scanning", 343 "malware-analysis", 344 "memory-analysis", 345 "network-analysis", 346 "leak", 347 "unknown" 348 ] 349 }, 350 "format": { 351 "description": "Format of the password(s)", 352 "ui-priority": 1, 353 "misp-attribute": "text", 354 "values_list": [ 355 "clear-text", 356 "hashed", 357 "encrypted", 358 "unknown" 359 ] 360 }, 361 "notification": { 362 "description": "Mention of any notification(s) towards the potential owner(s) of the credential(s)", 363 "ui-priority": 1, 364 "misp-attribute": "text", 365 "multiple": true, 366 "values_list": [ 367 "victim-notified", 368 "service-notified", 369 "none" 370 ] 371 } 372 }, 373 "version": 2, 374 "description": "Credential describes one or more credential(s) including password(s), api key(s) or decryption key(s).", 375 "meta-category": "misc", 376 "uuid": "a27e98c9-9b0e-414c-8076-d201e039ca09", 377 "name": "credential" 378 } 380 2.1.4. Object Relationships 382 2.1.4.1. name 384 name represents the human-readable relationship type which can be 385 used when creating MISP object relations. 387 name is represented as a JSON string. name MUST be present. 389 2.1.4.2. description 391 description is represented as a JSON string and contains the 392 description of the object relationship type. The description field 393 MUST be present. 395 2.1.4.3. format 397 format is represented by a JSON list containing a list of formats 398 that the relationship type is valid for and can be mapped to. The 399 format field MUST be present. 401 3. Directory 403 The MISP object template directory is publicly available [MISP-O] in 404 a git repository. The repository contains an objects directory, 405 which contains a directory per object type, containing a file named 406 definition.json which contains the definition of the object template 407 in the above described format. 409 A relationships directory is also included, containing a 410 definition.json file which contains a list of MISP object relation 411 definitions 413 4. Acknowledgements 415 The authors wish to thank all the MISP community who are supporting 416 the creation of open standards in threat intelligence sharing. 418 5. References 420 5.1. Normative References 422 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 423 Requirement Levels", BCP 14, RFC 2119, 424 DOI 10.17487/RFC2119, March 1997, 425 . 427 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 428 Unique IDentifier (UUID) URN Namespace", RFC 4122, 429 DOI 10.17487/RFC4122, July 2005, 430 . 432 [RFC4627] Crockford, D., "The application/json Media Type for 433 JavaScript Object Notation (JSON)", RFC 4627, 434 DOI 10.17487/RFC4627, July 2006, 435 . 437 5.2. Informative References 439 [MISP-O] MISP, "MISP Objects - shared and common object templates", 440 . 442 Authors' Addresses 444 Alexandre Dulaunoy 445 Computer Incident Response Center Luxembourg 446 16, bd d'Avranches 447 Luxembourg L-1611 448 Luxembourg 450 Phone: +352 247 88444 451 Email: alexandre.dulaunoy@circl.lu 453 Andras Iklody 454 Computer Incident Response Center Luxembourg 455 16, bd d'Avranches 456 Luxembourg L-1611 457 Luxembourg 459 Phone: +352 247 88444 460 Email: andras.iklody@circl.lu