idnits 2.17.1 draft-dulaunoy-misp-taxonomy-format-04.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 (November 29, 2017) is 2302 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: June 2, 2018 November 29, 2017 7 MISP taxonomy format 8 draft-dulaunoy-misp-taxonomy-format-04 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 June 2, 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 (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 Example use of the numerical_value in the MISP confidence level: 216 { 217 "predicate": "confidence-level", 218 "entry": [ 219 { 220 "expanded": "Completely confident", 221 "value": "completely-confident", 222 "numerical_value": 100 223 }, 224 { 225 "expanded": "Usually confident", 226 "value": "usually-confident", 227 "numerical_value": 75 228 }, 229 { 230 "expanded": "Fairly confident", 231 "value": "fairly-confident", 232 "numerical_value": 50 233 }, 234 { 235 "expanded": "Rarely confident", 236 "value": "rarely-confident", 237 "numerical_value": 25 238 }, 239 { 240 "expanded": "Unconfident", 241 "value": "unconfident", 242 "numerical_value": 0 243 }, 244 { 245 "expanded": "Confidence cannot be evaluated", 246 "value": "confidence-cannot-be-evalued" 247 } 248 ] 249 } 251 3. Directory 253 The MISP taxonomies directory is publicly available [MISP-T] in a git 254 repository. The repository contains a directory per namespace then a 255 file machinetag.json which contains the taxonomy as described in the 256 format above. In the root of the repository, a MANIFEST.json exists 257 containing a list of all the taxonomies. 259 The MANIFEST.json file is composed of an JSON object with metadata 260 like version, license, description, url and path. A taxonomies array 261 describes the taxonomy available with the description, name and 262 version field. 264 3.1. Sample Manifest 266 { 267 "version": "20161009", 268 "license": "CC-0", 269 "description": "Manifest file of MISP taxonomies available.", 270 "url": 271 "https://raw.githubusercontent.com/MISP/misp-taxonomies/master/", 272 "path": "machinetag.json", 273 "taxonomies": [ 274 { 275 "description": "The Admiralty Scale (also called the NATO System) 276 is used to rank the reliability of a source and 277 the credibility of an information.", 278 "name": "admiralty-scale", 279 "version": 1 280 }, 281 { 282 "description": "Open Source Intelligence - Classification.", 283 "name": "osint", 284 "version": 2 285 }] 286 } 288 4. Sample Taxonomy in MISP taxonomy format 290 4.1. Admiralty Scale Taxonomy 292 "namespace": "admiralty-scale", 293 "description": "The Admiralty Scale (also called the NATO System) 294 is used to rank the reliability of a source and 295 the credibility of an information.", 296 "version": 1, 297 "predicates": [ 298 { 299 "value": "source-reliability", 300 "expanded": "Source Reliability" 301 }, 302 { 303 "value": "information-credibility", 304 "expanded": "Information Credibility" 305 } 306 ], 307 "values": [ 308 { 309 "predicate": "source-reliability", 310 "entry": [ 311 { 312 "value": "a", 313 "expanded": "Completely reliable" 314 }, 315 { 316 "value": "b", 317 "expanded": "Usually reliable" 318 }, 319 { 320 "value": "c", 321 "expanded": "Fairly reliable" 322 }, 323 { 324 "value": "d", 325 "expanded": "Not usually reliable" 326 }, 327 { 328 "value": "e", 329 "expanded": "Unreliable" 330 }, 331 { 332 "value": "f", 333 "expanded": "Reliability cannot be judged" 334 } 335 ] 336 }, 337 { 338 "predicate": "information-credibility", 339 "entry": [ 340 { 341 "value": "1", 342 "expanded": "Confirmed by other sources" 343 }, 344 { 345 "value": "2", 346 "expanded": "Probably true" 347 }, 348 { 349 "value": "3", 350 "expanded": "Possibly true" 351 }, 352 { 353 "value": "4", 354 "expanded": "Doubtful" 355 }, 356 { 357 "value": "5", 358 "expanded": "Improbable" 359 }, 360 { 361 "value": "6", 362 "expanded": "Truth cannot be judged" 363 } 364 ] 365 } 366 ] 367 } 369 4.2. Open Source Intelligence - Classification 371 { 372 "values": [ 373 { 374 "entry": [ 375 { 376 "expanded": "Blog post", 377 "value": "blog-post" 378 }, 379 { 380 "expanded": "Technical or analysis report", 381 "value": "technical-report" 382 }, 383 { 384 "expanded": "News report", 385 "value": "news-report" 386 }, 387 { 388 "expanded": "Pastie-like website", 389 "value": "pastie-website" 390 }, 391 { 392 "expanded": "Electronic forum", 393 "value": "electronic-forum" 394 }, 395 { 396 "expanded": "Mailing-list", 397 "value": "mailing-list" 398 }, 399 { 400 "expanded": "Block or Filter List", 401 "value": "block-or-filter-list" 402 }, 403 { 404 "expanded": "Expansion", 405 "value": "expansion" 406 } 407 ], 408 "predicate": "source-type" 409 }, 410 { 411 "predicate": "lifetime", 412 "entry": [ 413 { 414 "value": "perpetual", 415 "expanded": "Perpetual", 416 "description": "Information available publicly on long-term" 417 }, 418 { 419 "value": "ephemeral", 420 "expanded": "Ephemeral", 421 "description": "Information available publicly on short-term" 422 } 423 ] 424 }, 425 { 426 "predicate": "certainty", 427 "entry": [ 428 { 429 "numerical_value": 100, 430 "value": "100", 431 "expanded": "100% Certainty", 432 "description": "100% Certainty" 433 }, 434 { 435 "numerical_value": 93, 436 "value": "93", 437 "expanded": "93% Almost certain", 438 "description": "93% Almost certain" 439 }, 440 { 441 "numerical_value": 75, 442 "value": "75", 443 "expanded": "75% Probable", 444 "description": "75% Probable" 445 }, 446 { 447 "numerical_value": 50, 448 "value": "50", 449 "expanded": "50% Chances about even", 450 "description": "50% Chances about even" 451 }, 452 { 453 "numerical_value": 30, 454 "value": "30", 455 "expanded": "30% Probably not", 456 "description": "30% Probably not" 457 }, 458 { 459 "numerical_value": 7, 460 "value": "7", 461 "expanded": "7% Almost certainly not", 462 "description": "7% Almost certainly not" 463 }, 464 { 465 "numerical_value": 0, 466 "value": "0", 467 "expanded": "0% Impossibility", 468 "description": "0% Impossibility" 469 } 470 ] 471 } 472 ], 473 "namespace": "osint", 474 "description": "Open Source Intelligence - Classification", 475 "version": 3, 476 "predicates": [ 477 { 478 "value": "source-type", 479 "expanded": "Source Type" 480 }, 481 { 482 "value": "lifetime", 483 "expanded": "Lifetime of the information 484 as Open Source Intelligence" 485 }, 486 { 487 "value": "certainty", 488 "expanded": "Certainty of the elements mentioned 489 in this Open Source Intelligence" 490 } 491 ] 492 } 494 5. JSON Schema 496 The JSON Schema [JSON-SCHEMA] below defines the structure of the MISP 497 taxonomy document as literally described before. The JSON Schema is 498 used validating a MISP taxonomy. The validation is a _MUST_ if the 499 taxonomy is included in the MISP taxonomies directory. 501 { 502 "$schema": "http://json-schema.org/schema#", 503 "title": "Validator for misp-taxonomies", 504 "id": "https://www.github.com/MISP/misp-taxonomies/schema.json", 505 "defs": { 506 "entry": { 507 "type": "array", 508 "uniqueItems": true, 509 "items": { 510 "type": "object", 511 "additionalProperties": false, 512 "properties": { 513 "numerical_value": { 514 "type": "number" 515 }, 516 "expanded": { 517 "type": "string" 518 }, 519 "description": { 520 "type": "string" 521 }, 522 "colour": { 523 "type": "string" 524 }, 525 "value": { 526 "type": "string" 527 }, 528 "required": [ 529 "value" 530 ] 531 } 532 } 533 }, 534 "values": { 535 "type": "array", 536 "uniqueItems": true, 537 "items": { 538 "type": "object", 539 "additionalProperties": false, 540 "properties": { 541 "entry": { 542 "$ref": "#/defs/entry" 543 }, 544 "predicate": { 545 "type": "string" 546 } 547 }, 548 "required": [ 549 "predicate" 550 ] 552 } 553 }, 554 "predicates": { 555 "type": "array", 556 "uniqueItems": true, 557 "items": { 558 "type": "object", 559 "additionalProperties": false, 560 "properties": { 561 "numerical_value": { 562 "type": "number" 563 }, 564 "colour": { 565 "type": "string" 566 }, 567 "description": { 568 "type": "string" 569 }, 570 "expanded": { 571 "type": "string" 572 }, 573 "value": { 574 "type": "string" 575 }, 576 "exclusive": { 577 "type": "boolean" 578 }, 579 "required": [ 580 "value" 581 ] 582 } 583 } 584 } 585 }, 586 "type": "object", 587 "additionalProperties": false, 588 "properties": { 589 "version": { 590 "type": "integer" 591 }, 592 "description": { 593 "type": "string" 594 }, 595 "expanded": { 596 "type": "string" 597 }, 598 "namespace": { 599 "type": "string" 601 }, 602 "exclusive": { 603 "type": "boolean" 604 }, 605 "type": { 606 "type": "array", 607 "uniqueItems": true, 608 "items": { 609 "type": "string", 610 "enum": [ 611 "org", 612 "user", 613 "attribute", 614 "event" 615 ] 616 } 617 }, 618 "refs": { 619 "type": "array", 620 "uniqueItems": true, 621 "items": { 622 "type": "string" 623 } 624 }, 625 "predicates": { 626 "$ref": "#/defs/predicates" 627 }, 628 "values": { 629 "$ref": "#/defs/values" 630 } 631 }, 632 "required": [ 633 "namespace", 634 "description", 635 "version", 636 "predicates" 637 ] 638 } 640 6. Acknowledgements 642 The authors wish to thank all the MISP community who are supporting 643 the creation of open standards in threat intelligence sharing. 645 7. References 647 7.1. Normative References 649 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 650 Requirement Levels", BCP 14, RFC 2119, 651 DOI 10.17487/RFC2119, March 1997, 652 . 654 [RFC4627] Crockford, D., "The application/json Media Type for 655 JavaScript Object Notation (JSON)", RFC 4627, 656 DOI 10.17487/RFC4627, July 2006, 657 . 659 7.2. Informative References 661 [JSON-SCHEMA] 662 "JSON Schema: A Media Type for Describing JSON Documents", 663 2016, 664 . 666 [machine-tags] 667 "Machine tags", 2007, 668 . 671 [MISP-P] MISP, "MISP Project - Malware Information Sharing Platform 672 and Threat Sharing", . 674 [MISP-T] MISP, "MISP Taxonomies - shared and common vocabularies of 675 tags", . 677 Authors' Addresses 679 Alexandre Dulaunoy 680 Computer Incident Response Center Luxembourg 681 16, bd d'Avranches 682 Luxembourg L-1611 683 Luxembourg 685 Phone: +352 247 88444 686 Email: alexandre.dulaunoy@circl.lu 687 Andras Iklody 688 Computer Incident Response Center Luxembourg 689 16, bd d'Avranches 690 Luxembourg L-1611 691 Luxembourg 693 Phone: +352 247 88444 694 Email: andras.iklody@circl.lu