diff --git a/misp-taxonomy-format/raw.md.txt b/misp-taxonomy-format/raw.md.txt new file mode 100644 index 0000000..73f2e31 --- /dev/null +++ b/misp-taxonomy-format/raw.md.txt @@ -0,0 +1,672 @@ + + + + +Network Working Group A. Dulaunoy +Internet-Draft A. Iklody +Intended status: Informational CIRCL +Expires: April 16, 2017 October 13, 2016 + + + MISP taxonomy format + draft-dulaunoy-misp-taxonomy-format + +Abstract + + This document describes the MISP taxonomy format which describes a + simple JSON format to represent machine tags (also called triple + tags) vocabularies. A public directory of common vocabularies MISP + taxonomies is available and relies on the MISP taxonomy format. + +Status of This Memo + + This Internet-Draft is submitted in full conformance with the + provisions of BCP 78 and BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF). Note that other groups may also distribute + working documents as Internet-Drafts. The list of current Internet- + Drafts is at http://datatracker.ietf.org/drafts/current/. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + This Internet-Draft will expire on April 16, 2017. + +Copyright Notice + + Copyright (c) 2016 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + + +Dulaunoy & Iklody Expires April 16, 2017 [Page 1] + +Internet-Draft MISP taxonomy format October 2016 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 + 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 3 + 2. Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2.2. predicates . . . . . . . . . . . . . . . . . . . . . . . 3 + 2.3. values . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 2.4. optional fields . . . . . . . . . . . . . . . . . . . . . 4 + 2.4.1. colour . . . . . . . . . . . . . . . . . . . . . . . 4 + 2.4.2. description . . . . . . . . . . . . . . . . . . . . . 4 + 2.4.3. numerical_value . . . . . . . . . . . . . . . . . . . 5 + 3. Directory . . . . . . . . . . . . . . . . . . . . . . . . . . 6 + 3.1. Sample Manifest . . . . . . . . . . . . . . . . . . . . . 6 + 4. Sample Taxonomy in MISP taxonomy format . . . . . . . . . . . 6 + 4.1. Admiralty Scale Taxonomy . . . . . . . . . . . . . . . . 6 + 4.2. Open Source Intelligence - Classification . . . . . . . . 8 + 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 + 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 6.1. Normative References . . . . . . . . . . . . . . . . . . 11 + 6.2. Informative References . . . . . . . . . . . . . . . . . 11 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 + +1. Introduction + + Sharing threat information became a fundamental requirements in the + Internet, security and intelligence community at large. Threat + information can include indicators of compromise, malicious file + indicators, financial fraud indicators or even detailed information + about a threat actor. While sharing such indicators or information, + classification plays an important role to ensure adequate + distribution, understanding, validation or action of the shared + information. MISP taxonomies is a public repository of known + vocabularies that can be used in threat information sharing. + + Machine tags were introduced in 2007 [machine-tags] to allow users to + be more precise when tagging their picture with geolocation. So a + machine tag is a tag which use a special syntax to provide more + information to user and machines. Machine tags are also known as + triple tags due to the their format. + + In MISP taxonomy context, machine tags help analysts to classify + their cybersecurity events, indicators or threats. MISP taxonomy can + be used for classification, filtering, triggering action or + visualization depending on their use in threat intelligence platforms + like MISP [MISP-P]. + + + + + +Dulaunoy & Iklody Expires April 16, 2017 [Page 2] + +Internet-Draft MISP taxonomy format October 2016 + + +1.1. Conventions and Terminology + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [RFC2119]. + +2. Format + + A machine tag is composed of a namespace (MUST), a predicate (MUST) + and an optional value (OPTIONAL). + + Machine tags are represented as a string. Below a set of sample + machine tags for different namespaces like tlp, admiralty-scale or + osint. + + tlp:amber + admiralty-scale:information-credibility="1" + osint:source-type="blog-post" + + The MISP taxonomy format describes how to define a machine tag + namespace in a parseable format. The objective is to provide a + simple format to describe machine tags (aka triple tags) + vocabularies. + +2.1. Overview + + The MISP taxonomy format uses the JSON [RFC4627] format. Each + namespace is represented as a JSON object with meta information + including the following fields namespace, description, version. + + namespace defines the overall namespace of the machine tag. The + namespace is represented as a string and MUST be present. The + description is represented as a string and SHOULD be present. A + version is represented as a decimal and MUST be present. + + predicates defines all the predicates available in the namespace + defined. predicates is represented as an array of JSON objects. + predicates MUST be present and MUST at least content one element. + + values defines all the values for each predicate in the namespace + defined. values SHOULD ne present. + +2.2. predicates + + predicates array contain one or more JSON objects which lists all the + possible predicate. The JSON object contains two fields: value and + expanded. value and expanded MUST be present. value is represented as + a string and describes the predicate value. The predicate value MUST + + + +Dulaunoy & Iklody Expires April 16, 2017 [Page 3] + +Internet-Draft MISP taxonomy format October 2016 + + + not contain spaces or colons. expanded is represented as a string and + describes the human-readable version of the predicate value. + +2.3. values + + values array contain one or more JSON objects which lists all the + possible values of a predicate. The JSON object contain two fields: + predicate and entry. predicate is represented as a string and + describes the predicate value. entry is an array with one or more + JSON objects. The JSON object contains two fields: value and + expanded. value and expanded MUST be present. value is represented as + a string and describe the value machine parsable. expanded is + represented as a string and describes the human-readable version of + the value. + +2.4. optional fields + +2.4.1. colour + + colour fields MAY be used at predicates or values level to set a + specify colour that *MAY** be used by the implementation. The colour + field is described as an RGB colour fill in hexadecimal + representation. + + Example use of the colour field in the Traffic Light Protocol (TLP): + + "predicates": [ + { + "colour": "#CC0033", + "expanded": "(TLP:RED) Information exclusively and directly + given to (a group of) individual recipients. + Sharing outside is not legitimate.", + "value": "red" + }, + { + "colour": "#FFC000", + "expanded": "(TLP:AMBER) Information exclusively given + to an organization; sharing limited within + the organization to be effectively acted upon.", + "value": "amber" + }...] + +2.4.2. description + + description fields MAY be used at predicates or values level to add a + descriptive and human-readable information about the specific + predicate or value. The field is represented as a string. + Implementations *_MAY_ use the description field to improve more + + + +Dulaunoy & Iklody Expires April 16, 2017 [Page 4] + +Internet-Draft MISP taxonomy format October 2016 + + + contextual information. The description at the namespace level is a + MUST as described above. + +2.4.3. numerical_value + + numerical_value fields MAY be used at predicates or values level to + add a machine-readable numeric value to a specific predicate or + value. The field is represented as JSON number. Implementations + SHOULD use the decimal value provided to support scoring or + filtering. + + Example use of the numerical_value in the MISP confidence level: + + { + "predicate": "confidence-level", + "entry": [ + { + "expanded": "Completely confident", + "value": "completely-confident", + "numerical_value": 100 + }, + { + "expanded": "Usually confident", + "value": "usually-confident", + "numerical_value": 75 + }, + { + "expanded": "Fairly confident", + "value": "fairly-confident", + "numerical_value": 50 + }, + { + "expanded": "Rarely confident", + "value": "rarely-confident", + "numerical_value": 25 + }, + { + "expanded": "Unconfident", + "value": "unconfident", + "numerical_value": 0 + }, + { + "expanded": "Confidence cannot be evaluated", + "value": "confidence-cannot-be-evalued" + } + ] + } + + + + +Dulaunoy & Iklody Expires April 16, 2017 [Page 5] + +Internet-Draft MISP taxonomy format October 2016 + + +3. Directory + + The MISP taxonomies directory is publicly available [MISP-T] in a git + repository. The repository contains a directory per namespace then a + file machinetag.json which contains the taxonomy as described in the + format above. In the root of the repository, a MANIFEST.json exists + containing a list of all the taxonomies. + + The MANIFEST.json file is composed of an JSON object with metadata + like version, license, description, url and path. A taxonomies array + describes the taxonomy available with the description, name and + version field. + +3.1. Sample Manifest + + { + "version": "20161009", + "license": "CC-0", + "description": "Manifest file of MISP taxonomies available.", + "url": + "https://raw.githubusercontent.com/MISP/misp-taxonomies/master/", + "path": "machinetag.json", + "taxonomies": [ + { + "description": "The Admiralty Scale (also called the NATO System) + is used to rank the reliability of a source and + the credibility of an information.", + "name": "admiralty-scale", + "version": 1 + }, + { + "description": "Open Source Intelligence - Classification.", + "name": "osint", + "version": 2 + }] + } + +4. Sample Taxonomy in MISP taxonomy format + +4.1. Admiralty Scale Taxonomy + + "namespace": "admiralty-scale", + "description": "The Admiralty Scale (also called the NATO System) + is used to rank the reliability of a source and + the credibility of an information.", + "version": 1, + "predicates": [ + { + + + +Dulaunoy & Iklody Expires April 16, 2017 [Page 6] + +Internet-Draft MISP taxonomy format October 2016 + + + "value": "source-reliability", + "expanded": "Source Reliability" + }, + { + "value": "information-credibility", + "expanded": "Information Credibility" + } + ], + "values": [ + { + "predicate": "source-reliability", + "entry": [ + { + "value": "a", + "expanded": "Completely reliable" + }, + { + "value": "b", + "expanded": "Usually reliable" + }, + { + "value": "c", + "expanded": "Fairly reliable" + }, + { + "value": "d", + "expanded": "Not usually reliable" + }, + { + "value": "e", + "expanded": "Unreliable" + }, + { + "value": "f", + "expanded": "Reliability cannot be judged" + } + ] + }, + { + "predicate": "information-credibility", + "entry": [ + { + "value": "1", + "expanded": "Confirmed by other sources" + }, + { + "value": "2", + "expanded": "Probably true" + + + +Dulaunoy & Iklody Expires April 16, 2017 [Page 7] + +Internet-Draft MISP taxonomy format October 2016 + + + }, + { + "value": "3", + "expanded": "Possibly true" + }, + { + "value": "4", + "expanded": "Doubtful" + }, + { + "value": "5", + "expanded": "Improbable" + }, + { + "value": "6", + "expanded": "Truth cannot be judged" + } + ] + } + ] + } + +4.2. Open Source Intelligence - Classification + + { + "values": [ + { + "entry": [ + { + "expanded": "Blog post", + "value": "blog-post" + }, + { + "expanded": "Technical or analysis report", + "value": "technical-report" + }, + { + "expanded": "News report", + "value": "news-report" + }, + { + "expanded": "Pastie-like website", + "value": "pastie-website" + }, + { + "expanded": "Electronic forum", + "value": "electronic-forum" + }, + + + +Dulaunoy & Iklody Expires April 16, 2017 [Page 8] + +Internet-Draft MISP taxonomy format October 2016 + + + { + "expanded": "Mailing-list", + "value": "mailing-list" + }, + { + "expanded": "Block or Filter List", + "value": "block-or-filter-list" + }, + { + "expanded": "Expansion", + "value": "expansion" + } + ], + "predicate": "source-type" + }, + { + "predicate": "lifetime", + "entry": [ + { + "value": "perpetual", + "expanded": "Perpetual", + "description": "Information available publicly on long-term" + }, + { + "value": "ephemeral", + "expanded": "Ephemeral", + "description": "Information available publicly on short-term" + } + ] + }, + { + "predicate": "certainty", + "entry": [ + { + "numerical_value": 100, + "value": "100", + "expanded": "100% Certainty", + "description": "100% Certainty" + }, + { + "numerical_value": 93, + "value": "93", + "expanded": "93% Almost certain", + "description": "93% Almost certain" + }, + { + "numerical_value": 75, + "value": "75", + + + +Dulaunoy & Iklody Expires April 16, 2017 [Page 9] + +Internet-Draft MISP taxonomy format October 2016 + + + "expanded": "75% Probable", + "description": "75% Probable" + }, + { + "numerical_value": 50, + "value": "50", + "expanded": "50% Chances about even", + "description": "50% Chances about even" + }, + { + "numerical_value": 30, + "value": "30", + "expanded": "30% Probably not", + "description": "30% Probably not" + }, + { + "numerical_value": 7, + "value": "7", + "expanded": "7% Almost certainly not", + "description": "7% Almost certainly not" + }, + { + "numerical_value": 0, + "value": "0", + "expanded": "0% Impossibility", + "description": "0% Impossibility" + } + ] + } + ], + "namespace": "osint", + "description": "Open Source Intelligence - Classification", + "version": 3, + "predicates": [ + { + "value": "source-type", + "expanded": "Source Type" + }, + { + "value": "lifetime", + "expanded": "Lifetime of the information + as Open Source Intelligence" + }, + { + "value": "certainty", + "expanded": "Certainty of the elements mentioned + in this Open Source Intelligence" + } + + + +Dulaunoy & Iklody Expires April 16, 2017 [Page 10] + +Internet-Draft MISP taxonomy format October 2016 + + + ] + } + + +5. Acknowledgements + + The authors wish to thank all the MISP community to support the + creation of open standards in threat intelligence sharing. + +6. References + +6.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC4627] Crockford, D., "The application/json Media Type for + JavaScript Object Notation (JSON)", RFC 4627, + DOI 10.17487/RFC4627, July 2006, + . + +6.2. Informative References + + [machine-tags] + "Machine tags", 2007, + . + + [MISP-P] MISP, , "MISP Project - Malware Information Sharing + Platform and Threat Sharing", . + + [MISP-T] MISP, , "MISP Taxonomies - shared and common vocabularies + of tags", . + +Authors' Addresses + + Alexandre Dulaunoy + Computer Incident Response Center Luxembourg + 41, avenue de la gare + Luxembourg L-1611 + Luxembourg + + Phone: +352 247 88444 + Email: alexandre.dulaunoy@circl.lu + + + + + +Dulaunoy & Iklody Expires April 16, 2017 [Page 11] + +Internet-Draft MISP taxonomy format October 2016 + + + Andras Iklody + Computer Incident Response Center Luxembourg + 41, avenue de la gare + Luxembourg L-1611 + Luxembourg + + Phone: +352 247 88444 + Email: andras.iklody@circl.lu + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Dulaunoy & Iklody Expires April 16, 2017 [Page 12]