idnits 2.17.1 draft-dulaunoy-misp-taxonomy-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.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The predicates array contains one or more JSON objects which lists all the possible predicates. The JSON object contains two fields: value and expanded. value MUST be present. expanded SHOULD be present. value is represented as a string and describes the predicate value. The predicate value MUST not contain spaces or colons. -- The document date (February 13, 2017) is 2628 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: 3 errors (**), 0 flaws (~~), 2 warnings (==), 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: August 17, 2017 February 13, 2017 7 MISP taxonomy format 8 draft-dulaunoy-misp-taxonomy-format-01 10 Abstract 12 This document describes the MISP taxonomy format which describes a 13 simple JSON format to represent machine tags (also called triple 14 tags) vocabularies. A public directory of common vocabularies MISP 15 taxonomies is available and relies on the MISP taxonomy format. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on August 17, 2017. 34 Copyright Notice 36 Copyright (c) 2017 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 3 53 2. Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2.2. predicates . . . . . . . . . . . . . . . . . . . . . . . 3 56 2.3. values . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 2.4. optional fields . . . . . . . . . . . . . . . . . . . . . 4 58 2.4.1. colour . . . . . . . . . . . . . . . . . . . . . . . 4 59 2.4.2. description . . . . . . . . . . . . . . . . . . . . . 4 60 2.4.3. numerical_value . . . . . . . . . . . . . . . . . . . 5 61 3. Directory . . . . . . . . . . . . . . . . . . . . . . . . . . 6 62 3.1. Sample Manifest . . . . . . . . . . . . . . . . . . . . . 6 63 4. Sample Taxonomy in MISP taxonomy format . . . . . . . . . . . 6 64 4.1. Admiralty Scale Taxonomy . . . . . . . . . . . . . . . . 6 65 4.2. Open Source Intelligence - Classification . . . . . . . . 8 66 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 67 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 68 6.1. Normative References . . . . . . . . . . . . . . . . . . 11 69 6.2. Informative References . . . . . . . . . . . . . . . . . 11 70 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 72 1. Introduction 74 Sharing threat information became a fundamental requirements on the 75 Internet, security and intelligence community at large. Threat 76 information can include indicators of compromise, malicious file 77 indicators, financial fraud indicators or even detailed information 78 about a threat actor. While sharing such indicators or information, 79 classification plays an important role to ensure adequate 80 distribution, understanding, validation or action of the shared 81 information. MISP taxonomies is a public repository of known 82 vocabularies that can be used in threat information sharing. 84 Machine tags were introduced in 2007 [machine-tags] to allow users to 85 be more precise when tagging their pictures with geolocation. So a 86 machine tag is a tag which uses a special syntax to provide more 87 information to users and machines. Machine tags are also known as 88 triple tags due to their format. 90 In the MISP taxonomy context, machine tags help analysts to classify 91 their cybersecurity events, indicators or threats. MISP taxonomies 92 can be used for classification, filtering, triggering actions or 93 visualisation depending on their use in threat intelligence platforms 94 such as MISP [MISP-P]. 96 1.1. Conventions and Terminology 98 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 99 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 100 document are to be interpreted as described in RFC 2119 [RFC2119]. 102 2. Format 104 A machine tag is composed of a namespace (MUST), a predicate (MUST) 105 and an optional value (OPTIONAL). 107 Machine tags are represented as a string. Below listed are a set of 108 sample machine tags for different namespaces such as tlp, admiralty- 109 scale and osint. 111 tlp:amber 112 admiralty-scale:information-credibility="1" 113 osint:source-type="blog-post" 115 The MISP taxonomy format describes how to define a machine tag 116 namespace in a parseable format. The objective is to provide a 117 simple format to describe machine tag (aka triple tag) vocabularies. 119 2.1. Overview 121 The MISP taxonomy format uses the JSON [RFC4627] format. Each 122 namespace is represented as a JSON object with meta information 123 including the following fields: namespace, description, version. 125 namespace defines the overall namespace of the machine tag. The 126 namespace is represented as a string and MUST be present. The 127 description is represented as a string and MUST be present. A 128 version is represented as a decimal and MUST be present. 130 predicates defines all the predicates available in the namespace 131 defined. predicates is represented as an array of JSON objects. 132 predicates MUST be present and MUST at least content one element. 134 values defines all the values for each predicate in the namespace 135 defined. values SHOULD be present. 137 2.2. predicates 139 The predicates array contains one or more JSON objects which lists 140 all the possible predicates. The JSON object contains two fields: 141 value and expanded. value MUST be present. expanded SHOULD be 142 present. value is represented as a string and describes the predicate 143 value. The predicate value MUST not contain spaces or colons. 145 expanded is represented as a string and describes the human-readable 146 version of the predicate value. 148 2.3. values 150 The values array contain one or more JSON objects which lists all the 151 possible values of a predicate. The JSON object contains two fields: 152 predicate and entry. predicate is represented as a string and 153 describes the predicate value. entry is an array with one or more 154 JSON objects. The JSON object contains two fields: value and 155 expanded. value MUST be present. expanded SHOULD be present. value is 156 represented as a string and describes the machine parsable value. 157 expanded is represented as a string and describes the human-readable 158 version of the value. 160 2.4. optional fields 162 2.4.1. colour 164 colour fields MAY be used at predicates or values level to set a 165 specify colour that MAY be used by the implementation. The colour 166 field is described as an RGB colour fill in hexadecimal 167 representation. 169 Example use of the colour field in the Traffic Light Protocol (TLP): 171 "predicates": [ 172 { 173 "colour": "#CC0033", 174 "expanded": "(TLP:RED) Information exclusively and directly 175 given to (a group of) individual recipients. 176 Sharing outside is not legitimate.", 177 "value": "red" 178 }, 179 { 180 "colour": "#FFC000", 181 "expanded": "(TLP:AMBER) Information exclusively given 182 to an organization; sharing limited within 183 the organization to be effectively acted upon.", 184 "value": "amber" 185 }...] 187 2.4.2. description 189 description fields MAY be used at predicates or values level to add a 190 descriptive and human-readable information about the specific 191 predicate or value. The field is represented as a string. 192 Implementations MAY use the description field to improve more 193 contextual information. The description at the namespace level is a 194 MUST as described above. 196 2.4.3. numerical_value 198 numerical_value fields MAY be used at a predicate or value level to 199 add a machine-readable numeric value to a specific predicate or 200 value. The field is represented as a JSON number. Implementations 201 SHOULD use the decimal value provided to support scoring or 202 filtering. 204 Example use of the numerical_value in the MISP confidence level: 206 { 207 "predicate": "confidence-level", 208 "entry": [ 209 { 210 "expanded": "Completely confident", 211 "value": "completely-confident", 212 "numerical_value": 100 213 }, 214 { 215 "expanded": "Usually confident", 216 "value": "usually-confident", 217 "numerical_value": 75 218 }, 219 { 220 "expanded": "Fairly confident", 221 "value": "fairly-confident", 222 "numerical_value": 50 223 }, 224 { 225 "expanded": "Rarely confident", 226 "value": "rarely-confident", 227 "numerical_value": 25 228 }, 229 { 230 "expanded": "Unconfident", 231 "value": "unconfident", 232 "numerical_value": 0 233 }, 234 { 235 "expanded": "Confidence cannot be evaluated", 236 "value": "confidence-cannot-be-evalued" 237 } 238 ] 239 } 241 3. Directory 243 The MISP taxonomies directory is publicly available [MISP-T] in a git 244 repository. The repository contains a directory per namespace then a 245 file machinetag.json which contains the taxonomy as described in the 246 format above. In the root of the repository, a MANIFEST.json exists 247 containing a list of all the taxonomies. 249 The MANIFEST.json file is composed of an JSON object with metadata 250 like version, license, description, url and path. A taxonomies array 251 describes the taxonomy available with the description, name and 252 version field. 254 3.1. Sample Manifest 256 { 257 "version": "20161009", 258 "license": "CC-0", 259 "description": "Manifest file of MISP taxonomies available.", 260 "url": 261 "https://raw.githubusercontent.com/MISP/misp-taxonomies/master/", 262 "path": "machinetag.json", 263 "taxonomies": [ 264 { 265 "description": "The Admiralty Scale (also called the NATO System) 266 is used to rank the reliability of a source and 267 the credibility of an information.", 268 "name": "admiralty-scale", 269 "version": 1 270 }, 271 { 272 "description": "Open Source Intelligence - Classification.", 273 "name": "osint", 274 "version": 2 275 }] 276 } 278 4. Sample Taxonomy in MISP taxonomy format 280 4.1. Admiralty Scale Taxonomy 282 "namespace": "admiralty-scale", 283 "description": "The Admiralty Scale (also called the NATO System) 284 is used to rank the reliability of a source and 285 the credibility of an information.", 286 "version": 1, 287 "predicates": [ 288 { 289 "value": "source-reliability", 290 "expanded": "Source Reliability" 291 }, 292 { 293 "value": "information-credibility", 294 "expanded": "Information Credibility" 295 } 296 ], 297 "values": [ 298 { 299 "predicate": "source-reliability", 300 "entry": [ 301 { 302 "value": "a", 303 "expanded": "Completely reliable" 304 }, 305 { 306 "value": "b", 307 "expanded": "Usually reliable" 308 }, 309 { 310 "value": "c", 311 "expanded": "Fairly reliable" 312 }, 313 { 314 "value": "d", 315 "expanded": "Not usually reliable" 316 }, 317 { 318 "value": "e", 319 "expanded": "Unreliable" 320 }, 321 { 322 "value": "f", 323 "expanded": "Reliability cannot be judged" 324 } 325 ] 326 }, 327 { 328 "predicate": "information-credibility", 329 "entry": [ 330 { 331 "value": "1", 332 "expanded": "Confirmed by other sources" 333 }, 334 { 335 "value": "2", 336 "expanded": "Probably true" 338 }, 339 { 340 "value": "3", 341 "expanded": "Possibly true" 342 }, 343 { 344 "value": "4", 345 "expanded": "Doubtful" 346 }, 347 { 348 "value": "5", 349 "expanded": "Improbable" 350 }, 351 { 352 "value": "6", 353 "expanded": "Truth cannot be judged" 354 } 355 ] 356 } 357 ] 358 } 360 4.2. Open Source Intelligence - Classification 362 { 363 "values": [ 364 { 365 "entry": [ 366 { 367 "expanded": "Blog post", 368 "value": "blog-post" 369 }, 370 { 371 "expanded": "Technical or analysis report", 372 "value": "technical-report" 373 }, 374 { 375 "expanded": "News report", 376 "value": "news-report" 377 }, 378 { 379 "expanded": "Pastie-like website", 380 "value": "pastie-website" 381 }, 382 { 383 "expanded": "Electronic forum", 384 "value": "electronic-forum" 385 }, 386 { 387 "expanded": "Mailing-list", 388 "value": "mailing-list" 389 }, 390 { 391 "expanded": "Block or Filter List", 392 "value": "block-or-filter-list" 393 }, 394 { 395 "expanded": "Expansion", 396 "value": "expansion" 397 } 398 ], 399 "predicate": "source-type" 400 }, 401 { 402 "predicate": "lifetime", 403 "entry": [ 404 { 405 "value": "perpetual", 406 "expanded": "Perpetual", 407 "description": "Information available publicly on long-term" 408 }, 409 { 410 "value": "ephemeral", 411 "expanded": "Ephemeral", 412 "description": "Information available publicly on short-term" 413 } 414 ] 415 }, 416 { 417 "predicate": "certainty", 418 "entry": [ 419 { 420 "numerical_value": 100, 421 "value": "100", 422 "expanded": "100% Certainty", 423 "description": "100% Certainty" 424 }, 425 { 426 "numerical_value": 93, 427 "value": "93", 428 "expanded": "93% Almost certain", 429 "description": "93% Almost certain" 430 }, 431 { 432 "numerical_value": 75, 433 "value": "75", 434 "expanded": "75% Probable", 435 "description": "75% Probable" 436 }, 437 { 438 "numerical_value": 50, 439 "value": "50", 440 "expanded": "50% Chances about even", 441 "description": "50% Chances about even" 442 }, 443 { 444 "numerical_value": 30, 445 "value": "30", 446 "expanded": "30% Probably not", 447 "description": "30% Probably not" 448 }, 449 { 450 "numerical_value": 7, 451 "value": "7", 452 "expanded": "7% Almost certainly not", 453 "description": "7% Almost certainly not" 454 }, 455 { 456 "numerical_value": 0, 457 "value": "0", 458 "expanded": "0% Impossibility", 459 "description": "0% Impossibility" 460 } 461 ] 462 } 463 ], 464 "namespace": "osint", 465 "description": "Open Source Intelligence - Classification", 466 "version": 3, 467 "predicates": [ 468 { 469 "value": "source-type", 470 "expanded": "Source Type" 471 }, 472 { 473 "value": "lifetime", 474 "expanded": "Lifetime of the information 475 as Open Source Intelligence" 476 }, 477 { 478 "value": "certainty", 479 "expanded": "Certainty of the elements mentioned 480 in this Open Source Intelligence" 481 } 483 ] 484 } 486 5. Acknowledgements 488 The authors wish to thank all the MISP community to support the 489 creation of open standards in threat intelligence sharing. 491 6. References 493 6.1. Normative References 495 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 496 Requirement Levels", BCP 14, RFC 2119, 497 DOI 10.17487/RFC2119, March 1997, 498 . 500 [RFC4627] Crockford, D., "The application/json Media Type for 501 JavaScript Object Notation (JSON)", RFC 4627, 502 DOI 10.17487/RFC4627, July 2006, 503 . 505 6.2. Informative References 507 [machine-tags] 508 "Machine tags", 2007, 509 . 512 [MISP-P] MISP, , "MISP Project - Malware Information Sharing 513 Platform and Threat Sharing", . 515 [MISP-T] MISP, , "MISP Taxonomies - shared and common vocabularies 516 of tags", . 518 Authors' Addresses 520 Alexandre Dulaunoy 521 Computer Incident Response Center Luxembourg 522 41, avenue de la gare 523 Luxembourg L-1611 524 Luxembourg 526 Phone: +352 247 88444 527 Email: alexandre.dulaunoy@circl.lu 528 Andras Iklody 529 Computer Incident Response Center Luxembourg 530 41, avenue de la gare 531 Luxembourg L-1611 532 Luxembourg 534 Phone: +352 247 88444 535 Email: andras.iklody@circl.lu