idnits 2.17.1 draft-dulaunoy-misp-taxonomy-format-03.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. expanded is represented as a string and describes the human-readable version of the predicate value. -- The document date (September 4, 2017) is 2425 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: March 8, 2018 September 4, 2017 7 MISP taxonomy format 8 draft-dulaunoy-misp-taxonomy-format-03 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. MISP 16 taxonomies are used to classify cyber security events, threats or 17 indicators. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on March 8, 2018. 36 Copyright Notice 38 Copyright (c) 2017 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 54 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 3 55 2. Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2.2. predicates . . . . . . . . . . . . . . . . . . . . . . . 4 58 2.3. values . . . . . . . . . . . . . . . . . . . . . . . . . 4 59 2.4. optional fields . . . . . . . . . . . . . . . . . . . . . 4 60 2.4.1. colour . . . . . . . . . . . . . . . . . . . . . . . 4 61 2.4.2. description . . . . . . . . . . . . . . . . . . . . . 5 62 2.4.3. numerical_value . . . . . . . . . . . . . . . . . . . 5 63 3. Directory . . . . . . . . . . . . . . . . . . . . . . . . . . 6 64 3.1. Sample Manifest . . . . . . . . . . . . . . . . . . . . . 7 65 4. Sample Taxonomy in MISP taxonomy format . . . . . . . . . . . 7 66 4.1. Admiralty Scale Taxonomy . . . . . . . . . . . . . . . . 7 67 4.2. Open Source Intelligence - Classification . . . . . . . . 9 68 5. JSON Schema . . . . . . . . . . . . . . . . . . . . . . . . . 11 69 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 14 70 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 71 7.1. Normative References . . . . . . . . . . . . . . . . . . 14 72 7.2. Informative References . . . . . . . . . . . . . . . . . 15 73 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 75 1. Introduction 77 Sharing threat information became a fundamental requirements on the 78 Internet, security and intelligence community at large. Threat 79 information can include indicators of compromise, malicious file 80 indicators, financial fraud indicators or even detailed information 81 about a threat actor. While sharing such indicators or information, 82 classification plays an important role to ensure adequate 83 distribution, understanding, validation or action of the shared 84 information. MISP taxonomies is a public repository of known 85 vocabularies that can be used in threat information sharing. 87 Machine tags were introduced in 2007 [machine-tags] to allow users to 88 be more precise when tagging their pictures with geolocation. So a 89 machine tag is a tag which uses a special syntax to provide more 90 information to users and machines. Machine tags are also known as 91 triple tags due to their format. 93 In the MISP taxonomy context, machine tags help analysts to classify 94 their cybersecurity events, indicators or threats. MISP taxonomies 95 can be used for classification, filtering, triggering actions or 96 visualisation depending on their use in threat intelligence platforms 97 such as MISP [MISP-P]. 99 1.1. Conventions and Terminology 101 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 102 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 103 document are to be interpreted as described in RFC 2119 [RFC2119]. 105 2. Format 107 A machine tag is composed of a namespace (MUST), a predicate (MUST) 108 and an optional value (OPTIONAL). 110 Machine tags are represented as a string. Below listed are a set of 111 sample machine tags for different namespaces such as tlp, admiralty- 112 scale and osint. 114 tlp:amber 115 admiralty-scale:information-credibility="1" 116 osint:source-type="blog-post" 118 The MISP taxonomy format describes how to define a machine tag 119 namespace in a parseable format. The objective is to provide a 120 simple format to describe machine tag (aka triple tag) vocabularies. 122 2.1. Overview 124 The MISP taxonomy format uses the JSON [RFC4627] format. Each 125 namespace is represented as a JSON object with meta information 126 including the following fields: namespace, description, version, 127 type. 129 namespace defines the overall namespace of the machine tag. The 130 namespace is represented as a string and MUST be present. The 131 description is represented as a string and MUST be present. A 132 version is represented as a decimal and MUST be present. A type 133 defines where a specific taxonomy is applicable and a type can be 134 applicable at event, user or org level. The type is represented as 135 an array containing one or more type and SHOULD be present. If a 136 type is not mentioned, by default, the taxonomy is applicable at 137 event level only. 139 predicates defines all the predicates available in the namespace 140 defined. predicates is represented as an array of JSON objects. 141 predicates MUST be present and MUST at least content one element. 143 values defines all the values for each predicate in the namespace 144 defined. values SHOULD be present. 146 2.2. predicates 148 The predicates array contains one or more JSON objects which lists 149 all the possible predicates. The JSON object contains two fields: 150 value and expanded. value MUST be present. expanded SHOULD be 151 present. value is represented as a string and describes the predicate 152 value. The predicate value MUST not contain spaces or colons. 153 expanded is represented as a string and describes the human-readable 154 version of the predicate value. 156 2.3. values 158 The values array contain one or more JSON objects which lists all the 159 possible values of a predicate. The JSON object contains two fields: 160 predicate and entry. predicate is represented as a string and 161 describes the predicate value. entry is an array with one or more 162 JSON objects. The JSON object contains two fields: value and 163 expanded. value MUST be present. expanded SHOULD be present. value is 164 represented as a string and describes the machine parsable value. 165 expanded is represented as a string and describes the human-readable 166 version of the value. 168 2.4. optional fields 170 2.4.1. colour 172 colour fields MAY be used at predicates or values level to set a 173 specify colour that MAY be used by the implementation. The colour 174 field is described as an RGB colour fill in hexadecimal 175 representation. 177 Example use of the colour field in the Traffic Light Protocol (TLP): 179 "predicates": [ 180 { 181 "colour": "#CC0033", 182 "expanded": "(TLP:RED) Information exclusively and directly 183 given to (a group of) individual recipients. 184 Sharing outside is not legitimate.", 185 "value": "red" 186 }, 187 { 188 "colour": "#FFC000", 189 "expanded": "(TLP:AMBER) Information exclusively given 190 to an organization; sharing limited within 191 the organization to be effectively acted upon.", 192 "value": "amber" 193 }...] 195 2.4.2. description 197 description fields MAY be used at predicates or values level to add a 198 descriptive and human-readable information about the specific 199 predicate or value. The field is represented as a string. 200 Implementations MAY use the description field to improve more 201 contextual information. The description at the namespace level is a 202 MUST as described above. 204 2.4.3. numerical_value 206 numerical_value fields MAY be used at a predicate or value level to 207 add a machine-readable numeric value to a specific predicate or 208 value. The field is represented as a JSON number. Implementations 209 SHOULD use the decimal value provided to support scoring or 210 filtering. 212 Example use of the numerical_value in the MISP confidence level: 214 { 215 "predicate": "confidence-level", 216 "entry": [ 217 { 218 "expanded": "Completely confident", 219 "value": "completely-confident", 220 "numerical_value": 100 221 }, 222 { 223 "expanded": "Usually confident", 224 "value": "usually-confident", 225 "numerical_value": 75 226 }, 227 { 228 "expanded": "Fairly confident", 229 "value": "fairly-confident", 230 "numerical_value": 50 231 }, 232 { 233 "expanded": "Rarely confident", 234 "value": "rarely-confident", 235 "numerical_value": 25 236 }, 237 { 238 "expanded": "Unconfident", 239 "value": "unconfident", 240 "numerical_value": 0 241 }, 242 { 243 "expanded": "Confidence cannot be evaluated", 244 "value": "confidence-cannot-be-evalued" 245 } 246 ] 247 } 249 3. Directory 251 The MISP taxonomies directory is publicly available [MISP-T] in a git 252 repository. The repository contains a directory per namespace then a 253 file machinetag.json which contains the taxonomy as described in the 254 format above. In the root of the repository, a MANIFEST.json exists 255 containing a list of all the taxonomies. 257 The MANIFEST.json file is composed of an JSON object with metadata 258 like version, license, description, url and path. A taxonomies array 259 describes the taxonomy available with the description, name and 260 version field. 262 3.1. Sample Manifest 264 { 265 "version": "20161009", 266 "license": "CC-0", 267 "description": "Manifest file of MISP taxonomies available.", 268 "url": 269 "https://raw.githubusercontent.com/MISP/misp-taxonomies/master/", 270 "path": "machinetag.json", 271 "taxonomies": [ 272 { 273 "description": "The Admiralty Scale (also called the NATO System) 274 is used to rank the reliability of a source and 275 the credibility of an information.", 276 "name": "admiralty-scale", 277 "version": 1 278 }, 279 { 280 "description": "Open Source Intelligence - Classification.", 281 "name": "osint", 282 "version": 2 283 }] 284 } 286 4. Sample Taxonomy in MISP taxonomy format 288 4.1. Admiralty Scale Taxonomy 290 "namespace": "admiralty-scale", 291 "description": "The Admiralty Scale (also called the NATO System) 292 is used to rank the reliability of a source and 293 the credibility of an information.", 294 "version": 1, 295 "predicates": [ 296 { 297 "value": "source-reliability", 298 "expanded": "Source Reliability" 299 }, 300 { 301 "value": "information-credibility", 302 "expanded": "Information Credibility" 303 } 304 ], 305 "values": [ 306 { 307 "predicate": "source-reliability", 308 "entry": [ 309 { 310 "value": "a", 311 "expanded": "Completely reliable" 312 }, 313 { 314 "value": "b", 315 "expanded": "Usually reliable" 316 }, 317 { 318 "value": "c", 319 "expanded": "Fairly reliable" 320 }, 321 { 322 "value": "d", 323 "expanded": "Not usually reliable" 324 }, 325 { 326 "value": "e", 327 "expanded": "Unreliable" 328 }, 329 { 330 "value": "f", 331 "expanded": "Reliability cannot be judged" 332 } 333 ] 334 }, 335 { 336 "predicate": "information-credibility", 337 "entry": [ 338 { 339 "value": "1", 340 "expanded": "Confirmed by other sources" 341 }, 342 { 343 "value": "2", 344 "expanded": "Probably true" 345 }, 346 { 347 "value": "3", 348 "expanded": "Possibly true" 349 }, 350 { 351 "value": "4", 352 "expanded": "Doubtful" 353 }, 354 { 355 "value": "5", 356 "expanded": "Improbable" 357 }, 358 { 359 "value": "6", 360 "expanded": "Truth cannot be judged" 361 } 362 ] 363 } 364 ] 365 } 367 4.2. Open Source Intelligence - Classification 369 { 370 "values": [ 371 { 372 "entry": [ 373 { 374 "expanded": "Blog post", 375 "value": "blog-post" 376 }, 377 { 378 "expanded": "Technical or analysis report", 379 "value": "technical-report" 380 }, 381 { 382 "expanded": "News report", 383 "value": "news-report" 384 }, 385 { 386 "expanded": "Pastie-like website", 387 "value": "pastie-website" 388 }, 389 { 390 "expanded": "Electronic forum", 391 "value": "electronic-forum" 392 }, 393 { 394 "expanded": "Mailing-list", 395 "value": "mailing-list" 396 }, 397 { 398 "expanded": "Block or Filter List", 399 "value": "block-or-filter-list" 400 }, 401 { 402 "expanded": "Expansion", 403 "value": "expansion" 404 } 405 ], 406 "predicate": "source-type" 407 }, 408 { 409 "predicate": "lifetime", 410 "entry": [ 411 { 412 "value": "perpetual", 413 "expanded": "Perpetual", 414 "description": "Information available publicly on long-term" 415 }, 416 { 417 "value": "ephemeral", 418 "expanded": "Ephemeral", 419 "description": "Information available publicly on short-term" 420 } 421 ] 422 }, 423 { 424 "predicate": "certainty", 425 "entry": [ 426 { 427 "numerical_value": 100, 428 "value": "100", 429 "expanded": "100% Certainty", 430 "description": "100% Certainty" 431 }, 432 { 433 "numerical_value": 93, 434 "value": "93", 435 "expanded": "93% Almost certain", 436 "description": "93% Almost certain" 437 }, 438 { 439 "numerical_value": 75, 440 "value": "75", 441 "expanded": "75% Probable", 442 "description": "75% Probable" 443 }, 444 { 445 "numerical_value": 50, 446 "value": "50", 447 "expanded": "50% Chances about even", 448 "description": "50% Chances about even" 449 }, 450 { 451 "numerical_value": 30, 452 "value": "30", 453 "expanded": "30% Probably not", 454 "description": "30% Probably not" 455 }, 456 { 457 "numerical_value": 7, 458 "value": "7", 459 "expanded": "7% Almost certainly not", 460 "description": "7% Almost certainly not" 461 }, 462 { 463 "numerical_value": 0, 464 "value": "0", 465 "expanded": "0% Impossibility", 466 "description": "0% Impossibility" 467 } 468 ] 469 } 470 ], 471 "namespace": "osint", 472 "description": "Open Source Intelligence - Classification", 473 "version": 3, 474 "predicates": [ 475 { 476 "value": "source-type", 477 "expanded": "Source Type" 478 }, 479 { 480 "value": "lifetime", 481 "expanded": "Lifetime of the information 482 as Open Source Intelligence" 483 }, 484 { 485 "value": "certainty", 486 "expanded": "Certainty of the elements mentioned 487 in this Open Source Intelligence" 488 } 489 ] 490 } 492 5. JSON Schema 494 The JSON Schema [JSON-SCHEMA] below defines the structure of the MISP 495 taxonomy document as literally described before. The JSON Schema is 496 used validating a MISP taxonomy. The validation is a _MUST_ if the 497 taxonomy is included in the MISP taxonomies directory. 499 { 500 "$schema": "http://json-schema.org/schema#", 501 "title": "Validator for misp-taxonomies", 502 "id": "https://www.github.com/MISP/misp-taxonomies/schema.json", 503 "defs": { 504 "entry": { 505 "type": "array", 506 "uniqueItems": true, 507 "items": { 508 "type": "object", 509 "additionalProperties": false, 510 "properties": { 511 "numerical_value": { 512 "type": "number" 513 }, 514 "expanded": { 515 "type": "string" 516 }, 517 "description": { 518 "type": "string" 519 }, 520 "colour": { 521 "type": "string" 522 }, 523 "value": { 524 "type": "string" 525 }, 526 "required": [ 527 "value" 528 ] 529 } 530 } 531 }, 532 "values": { 533 "type": "array", 534 "uniqueItems": true, 535 "items": { 536 "type": "object", 537 "additionalProperties": false, 538 "properties": { 539 "entry": { 540 "$ref": "#/defs/entry" 541 }, 542 "predicate": { 543 "type": "string" 544 } 545 }, 546 "required": [ 547 "predicate" 548 ] 550 } 551 }, 552 "predicates": { 553 "type": "array", 554 "uniqueItems": true, 555 "items": { 556 "type": "object", 557 "additionalProperties": false, 558 "properties": { 559 "numerical_value": { 560 "type": "number" 561 }, 562 "colour": { 563 "type": "string" 564 }, 565 "description": { 566 "type": "string" 567 }, 568 "expanded": { 569 "type": "string" 570 }, 571 "value": { 572 "type": "string" 573 }, 574 "required": [ 575 "value" 576 ] 577 } 578 } 579 } 580 }, 581 "type": "object", 582 "additionalProperties": false, 583 "properties": { 584 "version": { 585 "type": "integer" 586 }, 587 "description": { 588 "type": "string" 589 }, 590 "expanded": { 591 "type": "string" 592 }, 593 "namespace": { 594 "type": "string" 595 }, 596 "type": { 597 "type": "array", 598 "uniqueItems": true, 599 "items": { 600 "type": "string", 601 "enum": [ 602 "org", 603 "user", 604 "attribute", 605 "event" 606 ] 607 } 608 }, 609 "refs": { 610 "type": "array", 611 "uniqueItems": true, 612 "items": { 613 "type": "string" 614 } 615 }, 616 "predicates": { 617 "$ref": "#/defs/predicates" 618 }, 619 "values": { 620 "$ref": "#/defs/values" 621 } 622 }, 623 "required": [ 624 "namespace", 625 "description", 626 "version", 627 "predicates" 628 ] 629 } 631 6. Acknowledgements 633 The authors wish to thank all the MISP community to support the 634 creation of open standards in threat intelligence sharing. 636 7. References 638 7.1. Normative References 640 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 641 Requirement Levels", BCP 14, RFC 2119, 642 DOI 10.17487/RFC2119, March 1997, . 645 [RFC4627] Crockford, D., "The application/json Media Type for 646 JavaScript Object Notation (JSON)", RFC 4627, 647 DOI 10.17487/RFC4627, July 2006, . 650 7.2. Informative References 652 [JSON-SCHEMA] 653 "JSON Schema: A Media Type for Describing JSON Documents", 654 2016, . 657 [machine-tags] 658 "Machine tags", 2007, 659 . 662 [MISP-P] MISP, "MISP Project - Malware Information Sharing Platform 663 and Threat Sharing", . 665 [MISP-T] MISP, "MISP Taxonomies - shared and common vocabularies of 666 tags", . 668 Authors' Addresses 670 Alexandre Dulaunoy 671 Computer Incident Response Center Luxembourg 672 16, bd d'Avranches 673 Luxembourg L-1611 674 Luxembourg 676 Phone: +352 247 88444 677 Email: alexandre.dulaunoy@circl.lu 679 Andras Iklody 680 Computer Incident Response Center Luxembourg 681 16, bd d'Avranches 682 Luxembourg L-1611 683 Luxembourg 685 Phone: +352 247 88444 686 Email: andras.iklody@circl.lu