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