idnits 2.17.1 draft-dulaunoy-misp-taxonomy-format-05.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. An exclusive property MAY be present and defines at namespace level if the values are mutually exclusive. -- The document date (June 01, 2018) is 2153 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: December 3, 2018 June 01, 2018 7 MISP taxonomy format 8 draft-dulaunoy-misp-taxonomy-format-05 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 https://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 December 3, 2018. 36 Copyright Notice 38 Copyright (c) 2018 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 (https://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 . . . . . . . . . . . . . . . . . . . . . . . . . 15 71 7.1. Normative References . . . . . . . . . . . . . . . . . . 15 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. An exclusive boolean property MAY be present and 138 defines at namespace level if the predicates are mutually exclusive. 140 predicates defines all the predicates available in the namespace 141 defined. predicates is represented as an array of JSON objects. 142 predicates MUST be present and MUST at least content one element. 144 values defines all the values for each predicate in the namespace 145 defined. values SHOULD be present. 147 2.2. predicates 149 The predicates array contains one or more JSON objects which lists 150 all the possible predicates. The JSON object contains two fields: 151 value and expanded. value MUST be present. expanded SHOULD be 152 present. value is represented as a string and describes the predicate 153 value. The predicate value MUST not contain spaces or colons. 154 expanded is represented as a string and describes the human-readable 155 version of the predicate value. An exclusive property MAY be present 156 and defines at namespace level if the values are mutually exclusive. 158 2.3. values 160 The values array contain one or more JSON objects which lists all the 161 possible values of a predicate. The JSON object contains two fields: 162 predicate and entry. predicate is represented as a string and 163 describes the predicate value. entry is an array with one or more 164 JSON objects. The JSON object contains two fields: value and 165 expanded. value MUST be present. expanded SHOULD be present. value is 166 represented as a string and describes the machine parsable value. 167 expanded is represented as a string and describes the human-readable 168 version of the value. 170 2.4. optional fields 172 2.4.1. colour 174 colour fields MAY be used at predicates or values level to set a 175 specify colour that MAY be used by the implementation. The colour 176 field is described as an RGB colour fill in hexadecimal 177 representation. 179 Example use of the colour field in the Traffic Light Protocol (TLP): 181 "predicates": [ 182 { 183 "colour": "#CC0033", 184 "expanded": "(TLP:RED) Information exclusively and directly 185 given to (a group of) individual recipients. 186 Sharing outside is not legitimate.", 187 "value": "red" 188 }, 189 { 190 "colour": "#FFC000", 191 "expanded": "(TLP:AMBER) Information exclusively given 192 to an organization; sharing limited within 193 the organization to be effectively acted upon.", 194 "value": "amber" 195 }...] 197 2.4.2. description 199 description fields MAY be used at predicates or values level to add a 200 descriptive and human-readable information about the specific 201 predicate or value. The field is represented as a string. 202 Implementations MAY use the description field to improve more 203 contextual information. The description at the namespace level is a 204 MUST as described above. 206 2.4.3. numerical_value 208 numerical_value fields MAY be used at a predicate or value level to 209 add a machine-readable numeric value to a specific predicate or 210 value. The field is represented as a JSON number. Implementations 211 SHOULD use the decimal value provided to support scoring or 212 filtering. 214 The decimal range for numerical_value SHOULD use a range from 0 up to 215 100. The range is recommended to support common mathematical 216 properties among taxonomies. 218 Example use of the numerical_value in the MISP confidence level: 220 { 221 "predicate": "confidence-level", 222 "entry": [ 223 { 224 "expanded": "Completely confident", 225 "value": "completely-confident", 226 "numerical_value": 100 227 }, 228 { 229 "expanded": "Usually confident", 230 "value": "usually-confident", 231 "numerical_value": 75 232 }, 233 { 234 "expanded": "Fairly confident", 235 "value": "fairly-confident", 236 "numerical_value": 50 237 }, 238 { 239 "expanded": "Rarely confident", 240 "value": "rarely-confident", 241 "numerical_value": 25 242 }, 243 { 244 "expanded": "Unconfident", 245 "value": "unconfident", 246 "numerical_value": 0 247 }, 248 { 249 "expanded": "Confidence cannot be evaluated", 250 "value": "confidence-cannot-be-evalued" 251 } 252 ] 253 } 255 3. Directory 257 The MISP taxonomies directory is publicly available [MISP-T] in a git 258 repository. The repository contains a directory per namespace then a 259 file machinetag.json which contains the taxonomy as described in the 260 format above. In the root of the repository, a MANIFEST.json exists 261 containing a list of all the taxonomies. 263 The MANIFEST.json file is composed of an JSON object with metadata 264 like version, license, description, url and path. A taxonomies array 265 describes the taxonomy available with the description, name and 266 version field. 268 3.1. Sample Manifest 270 { 271 "version": "20161009", 272 "license": "CC-0", 273 "description": "Manifest file of MISP taxonomies available.", 274 "url": 275 "https://raw.githubusercontent.com/MISP/misp-taxonomies/master/", 276 "path": "machinetag.json", 277 "taxonomies": [ 278 { 279 "description": "The Admiralty Scale (also called the NATO System) 280 is used to rank the reliability of a source and 281 the credibility of an information.", 282 "name": "admiralty-scale", 283 "version": 1 284 }, 285 { 286 "description": "Open Source Intelligence - Classification.", 287 "name": "osint", 288 "version": 2 289 }] 290 } 292 4. Sample Taxonomy in MISP taxonomy format 294 4.1. Admiralty Scale Taxonomy 296 "namespace": "admiralty-scale", 297 "description": "The Admiralty Scale (also called the NATO System) 298 is used to rank the reliability of a source and 299 the credibility of an information.", 300 "version": 1, 301 "predicates": [ 302 { 303 "value": "source-reliability", 304 "expanded": "Source Reliability" 305 }, 306 { 307 "value": "information-credibility", 308 "expanded": "Information Credibility" 309 } 310 ], 311 "values": [ 312 { 313 "predicate": "source-reliability", 314 "entry": [ 315 { 316 "value": "a", 317 "expanded": "Completely reliable" 318 }, 319 { 320 "value": "b", 321 "expanded": "Usually reliable" 322 }, 323 { 324 "value": "c", 325 "expanded": "Fairly reliable" 326 }, 327 { 328 "value": "d", 329 "expanded": "Not usually reliable" 330 }, 331 { 332 "value": "e", 333 "expanded": "Unreliable" 334 }, 335 { 336 "value": "f", 337 "expanded": "Reliability cannot be judged" 338 } 339 ] 340 }, 341 { 342 "predicate": "information-credibility", 343 "entry": [ 344 { 345 "value": "1", 346 "expanded": "Confirmed by other sources" 347 }, 348 { 349 "value": "2", 350 "expanded": "Probably true" 351 }, 352 { 353 "value": "3", 354 "expanded": "Possibly true" 355 }, 356 { 357 "value": "4", 358 "expanded": "Doubtful" 359 }, 360 { 361 "value": "5", 362 "expanded": "Improbable" 363 }, 364 { 365 "value": "6", 366 "expanded": "Truth cannot be judged" 367 } 368 ] 369 } 370 ] 371 } 373 4.2. Open Source Intelligence - Classification 375 { 376 "values": [ 377 { 378 "entry": [ 379 { 380 "expanded": "Blog post", 381 "value": "blog-post" 382 }, 383 { 384 "expanded": "Technical or analysis report", 385 "value": "technical-report" 386 }, 387 { 388 "expanded": "News report", 389 "value": "news-report" 390 }, 391 { 392 "expanded": "Pastie-like website", 393 "value": "pastie-website" 394 }, 395 { 396 "expanded": "Electronic forum", 397 "value": "electronic-forum" 398 }, 399 { 400 "expanded": "Mailing-list", 401 "value": "mailing-list" 402 }, 403 { 404 "expanded": "Block or Filter List", 405 "value": "block-or-filter-list" 406 }, 407 { 408 "expanded": "Expansion", 409 "value": "expansion" 410 } 411 ], 412 "predicate": "source-type" 413 }, 414 { 415 "predicate": "lifetime", 416 "entry": [ 417 { 418 "value": "perpetual", 419 "expanded": "Perpetual", 420 "description": "Information available publicly on long-term" 421 }, 422 { 423 "value": "ephemeral", 424 "expanded": "Ephemeral", 425 "description": "Information available publicly on short-term" 426 } 427 ] 428 }, 429 { 430 "predicate": "certainty", 431 "entry": [ 432 { 433 "numerical_value": 100, 434 "value": "100", 435 "expanded": "100% Certainty", 436 "description": "100% Certainty" 437 }, 438 { 439 "numerical_value": 93, 440 "value": "93", 441 "expanded": "93% Almost certain", 442 "description": "93% Almost certain" 443 }, 444 { 445 "numerical_value": 75, 446 "value": "75", 447 "expanded": "75% Probable", 448 "description": "75% Probable" 449 }, 450 { 451 "numerical_value": 50, 452 "value": "50", 453 "expanded": "50% Chances about even", 454 "description": "50% Chances about even" 455 }, 456 { 457 "numerical_value": 30, 458 "value": "30", 459 "expanded": "30% Probably not", 460 "description": "30% Probably not" 461 }, 462 { 463 "numerical_value": 7, 464 "value": "7", 465 "expanded": "7% Almost certainly not", 466 "description": "7% Almost certainly not" 467 }, 468 { 469 "numerical_value": 0, 470 "value": "0", 471 "expanded": "0% Impossibility", 472 "description": "0% Impossibility" 473 } 474 ] 475 } 476 ], 477 "namespace": "osint", 478 "description": "Open Source Intelligence - Classification", 479 "version": 3, 480 "predicates": [ 481 { 482 "value": "source-type", 483 "expanded": "Source Type" 484 }, 485 { 486 "value": "lifetime", 487 "expanded": "Lifetime of the information 488 as Open Source Intelligence" 489 }, 490 { 491 "value": "certainty", 492 "expanded": "Certainty of the elements mentioned 493 in this Open Source Intelligence" 494 } 495 ] 496 } 498 5. JSON Schema 500 The JSON Schema [JSON-SCHEMA] below defines the structure of the MISP 501 taxonomy document as literally described before. The JSON Schema is 502 used validating a MISP taxonomy. The validation is a _MUST_ if the 503 taxonomy is included in the MISP taxonomies directory. 505 { 506 "$schema": "http://json-schema.org/schema#", 507 "title": "Validator for misp-taxonomies", 508 "id": "https://www.github.com/MISP/misp-taxonomies/schema.json", 509 "defs": { 510 "entry": { 511 "type": "array", 512 "uniqueItems": true, 513 "items": { 514 "type": "object", 515 "additionalProperties": false, 516 "properties": { 517 "numerical_value": { 518 "type": "number" 519 }, 520 "expanded": { 521 "type": "string" 522 }, 523 "description": { 524 "type": "string" 525 }, 526 "colour": { 527 "type": "string" 528 }, 529 "value": { 530 "type": "string" 531 }, 532 "required": [ 533 "value" 534 ] 535 } 536 } 537 }, 538 "values": { 539 "type": "array", 540 "uniqueItems": true, 541 "items": { 542 "type": "object", 543 "additionalProperties": false, 544 "properties": { 545 "entry": { 546 "$ref": "#/defs/entry" 547 }, 548 "predicate": { 549 "type": "string" 550 } 551 }, 552 "required": [ 553 "predicate" 554 ] 556 } 557 }, 558 "predicates": { 559 "type": "array", 560 "uniqueItems": true, 561 "items": { 562 "type": "object", 563 "additionalProperties": false, 564 "properties": { 565 "numerical_value": { 566 "type": "number" 567 }, 568 "colour": { 569 "type": "string" 570 }, 571 "description": { 572 "type": "string" 573 }, 574 "expanded": { 575 "type": "string" 576 }, 577 "value": { 578 "type": "string" 579 }, 580 "exclusive": { 581 "type": "boolean" 582 }, 583 "required": [ 584 "value" 585 ] 586 } 587 } 588 } 589 }, 590 "type": "object", 591 "additionalProperties": false, 592 "properties": { 593 "version": { 594 "type": "integer" 595 }, 596 "description": { 597 "type": "string" 598 }, 599 "expanded": { 600 "type": "string" 601 }, 602 "namespace": { 603 "type": "string" 605 }, 606 "exclusive": { 607 "type": "boolean" 608 }, 609 "type": { 610 "type": "array", 611 "uniqueItems": true, 612 "items": { 613 "type": "string", 614 "enum": [ 615 "org", 616 "user", 617 "attribute", 618 "event" 619 ] 620 } 621 }, 622 "refs": { 623 "type": "array", 624 "uniqueItems": true, 625 "items": { 626 "type": "string" 627 } 628 }, 629 "predicates": { 630 "$ref": "#/defs/predicates" 631 }, 632 "values": { 633 "$ref": "#/defs/values" 634 } 635 }, 636 "required": [ 637 "namespace", 638 "description", 639 "version", 640 "predicates" 641 ] 642 } 644 6. Acknowledgements 646 The authors wish to thank all the MISP community who are supporting 647 the creation of open standards in threat intelligence sharing. 649 7. References 651 7.1. Normative References 653 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 654 Requirement Levels", BCP 14, RFC 2119, 655 DOI 10.17487/RFC2119, March 1997, 656 . 658 [RFC4627] Crockford, D., "The application/json Media Type for 659 JavaScript Object Notation (JSON)", RFC 4627, 660 DOI 10.17487/RFC4627, July 2006, 661 . 663 7.2. Informative References 665 [JSON-SCHEMA] 666 "JSON Schema: A Media Type for Describing JSON Documents", 667 2016, 668 . 670 [machine-tags] 671 "Machine tags", 2007, 672 . 675 [MISP-P] MISP, "MISP Project - Malware Information Sharing Platform 676 and Threat Sharing", . 678 [MISP-T] MISP, "MISP Taxonomies - shared and common vocabularies of 679 tags", . 681 Authors' Addresses 683 Alexandre Dulaunoy 684 Computer Incident Response Center Luxembourg 685 16, bd d'Avranches 686 Luxembourg L-1611 687 Luxembourg 689 Phone: +352 247 88444 690 Email: alexandre.dulaunoy@circl.lu 691 Andras Iklody 692 Computer Incident Response Center Luxembourg 693 16, bd d'Avranches 694 Luxembourg L-1611 695 Luxembourg 697 Phone: +352 247 88444 698 Email: andras.iklody@circl.lu