From 088eff88f8cea51b5d4885f4dd870630b9bef212 Mon Sep 17 00:00:00 2001 From: Alexandre Dulaunoy Date: Tue, 11 Apr 2017 09:00:44 +0200 Subject: [PATCH] JSON Schema added --- misp-taxonomy-format/raw.md.txt | 420 ++++++++++++++++++++++---------- 1 file changed, 294 insertions(+), 126 deletions(-) diff --git a/misp-taxonomy-format/raw.md.txt b/misp-taxonomy-format/raw.md.txt index 7d74aa4..8779ac7 100644 --- a/misp-taxonomy-format/raw.md.txt +++ b/misp-taxonomy-format/raw.md.txt @@ -5,7 +5,7 @@ Network Working Group A. Dulaunoy Internet-Draft A. Iklody Intended status: Informational CIRCL -Expires: August 17, 2017 February 13, 2017 +Expires: October 12, 2017 April 10, 2017 MISP taxonomy format @@ -16,7 +16,9 @@ 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. + taxonomies is available and relies on the MISP taxonomy format. MISP + taxonomies are used to classify cyber security events, threats or + indicators. Status of This Memo @@ -33,7 +35,7 @@ Status of This Memo 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 August 17, 2017. + This Internet-Draft will expire on October 12, 2017. Copyright Notice @@ -47,39 +49,41 @@ Copyright Notice 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 + + + + +Dulaunoy & Iklody Expires October 12, 2017 [Page 1] + +Internet-Draft MISP taxonomy format April 2017 + + the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. - - - -Dulaunoy & Iklody Expires August 17, 2017 [Page 1] - -Internet-Draft MISP taxonomy format February 2017 - - Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 3 2. Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 3 - 2.2. predicates . . . . . . . . . . . . . . . . . . . . . . . 3 + 2.2. predicates . . . . . . . . . . . . . . . . . . . . . . . 4 2.3. values . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.4. optional fields . . . . . . . . . . . . . . . . . . . . . 4 2.4.1. colour . . . . . . . . . . . . . . . . . . . . . . . 4 - 2.4.2. description . . . . . . . . . . . . . . . . . . . . . 4 + 2.4.2. description . . . . . . . . . . . . . . . . . . . . . 5 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 + 3.1. Sample Manifest . . . . . . . . . . . . . . . . . . . . . 7 + 4. Sample Taxonomy in MISP taxonomy format . . . . . . . . . . . 7 + 4.1. Admiralty Scale Taxonomy . . . . . . . . . . . . . . . . 7 + 4.2. Open Source Intelligence - Classification . . . . . . . . 9 + 5. JSON Schema . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 14 + 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 + 7.1. Normative References . . . . . . . . . . . . . . . . . . 14 + 7.2. Informative References . . . . . . . . . . . . . . . . . 14 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 1. Introduction @@ -102,18 +106,17 @@ Table of Contents In the MISP taxonomy context, machine tags help analysts to classify their cybersecurity events, indicators or threats. MISP taxonomies can be used for classification, filtering, triggering actions or + + + +Dulaunoy & Iklody Expires October 12, 2017 [Page 2] + +Internet-Draft MISP taxonomy format April 2017 + + visualisation depending on their use in threat intelligence platforms such as MISP [MISP-P]. - - - - -Dulaunoy & Iklody Expires August 17, 2017 [Page 2] - -Internet-Draft MISP taxonomy format February 2017 - - 1.1. Conventions and Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", @@ -155,6 +158,18 @@ Internet-Draft MISP taxonomy format February 2017 values defines all the values for each predicate in the namespace defined. values SHOULD be present. + + + + + + + +Dulaunoy & Iklody Expires October 12, 2017 [Page 3] + +Internet-Draft MISP taxonomy format April 2017 + + 2.2. predicates The predicates array contains one or more JSON objects which lists @@ -162,14 +177,6 @@ Internet-Draft MISP taxonomy format February 2017 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. - - - -Dulaunoy & Iklody Expires August 17, 2017 [Page 3] - -Internet-Draft MISP taxonomy format February 2017 - - expanded is represented as a string and describes the human-readable version of the predicate value. @@ -212,20 +219,19 @@ Internet-Draft MISP taxonomy format February 2017 "value": "amber" }...] + + +Dulaunoy & Iklody Expires October 12, 2017 [Page 4] + +Internet-Draft MISP taxonomy format April 2017 + + 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 August 17, 2017 [Page 4] - -Internet-Draft MISP taxonomy format February 2017 - - contextual information. The description at the namespace level is a MUST as described above. @@ -239,6 +245,43 @@ Internet-Draft MISP taxonomy format February 2017 Example use of the numerical_value in the MISP confidence level: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Dulaunoy & Iklody Expires October 12, 2017 [Page 5] + +Internet-Draft MISP taxonomy format April 2017 + + { "predicate": "confidence-level", "entry": [ @@ -274,14 +317,6 @@ Internet-Draft MISP taxonomy format February 2017 ] } - - - -Dulaunoy & Iklody Expires August 17, 2017 [Page 5] - -Internet-Draft MISP taxonomy format February 2017 - - 3. Directory The MISP taxonomies directory is publicly available [MISP-T] in a git @@ -295,6 +330,14 @@ Internet-Draft MISP taxonomy format February 2017 describes the taxonomy available with the description, name and version field. + + + +Dulaunoy & Iklody Expires October 12, 2017 [Page 6] + +Internet-Draft MISP taxonomy format April 2017 + + 3.1. Sample Manifest { @@ -330,14 +373,6 @@ Internet-Draft MISP taxonomy format February 2017 "version": 1, "predicates": [ { - - - -Dulaunoy & Iklody Expires August 17, 2017 [Page 6] - -Internet-Draft MISP taxonomy format February 2017 - - "value": "source-reliability", "expanded": "Source Reliability" }, @@ -351,6 +386,14 @@ Internet-Draft MISP taxonomy format February 2017 "predicate": "source-reliability", "entry": [ { + + + +Dulaunoy & Iklody Expires October 12, 2017 [Page 7] + +Internet-Draft MISP taxonomy format April 2017 + + "value": "a", "expanded": "Completely reliable" }, @@ -386,14 +429,6 @@ Internet-Draft MISP taxonomy format February 2017 { "value": "2", "expanded": "Probably true" - - - -Dulaunoy & Iklody Expires August 17, 2017 [Page 7] - -Internet-Draft MISP taxonomy format February 2017 - - }, { "value": "3", @@ -407,6 +442,14 @@ Internet-Draft MISP taxonomy format February 2017 "value": "5", "expanded": "Improbable" }, + + + +Dulaunoy & Iklody Expires October 12, 2017 [Page 8] + +Internet-Draft MISP taxonomy format April 2017 + + { "value": "6", "expanded": "Truth cannot be judged" @@ -442,14 +485,6 @@ Internet-Draft MISP taxonomy format February 2017 "expanded": "Electronic forum", "value": "electronic-forum" }, - - - -Dulaunoy & Iklody Expires August 17, 2017 [Page 8] - -Internet-Draft MISP taxonomy format February 2017 - - { "expanded": "Mailing-list", "value": "mailing-list" @@ -463,6 +498,14 @@ Internet-Draft MISP taxonomy format February 2017 "value": "expansion" } ], + + + +Dulaunoy & Iklody Expires October 12, 2017 [Page 9] + +Internet-Draft MISP taxonomy format April 2017 + + "predicate": "source-type" }, { @@ -498,14 +541,6 @@ Internet-Draft MISP taxonomy format February 2017 { "numerical_value": 75, "value": "75", - - - -Dulaunoy & Iklody Expires August 17, 2017 [Page 9] - -Internet-Draft MISP taxonomy format February 2017 - - "expanded": "75% Probable", "description": "75% Probable" }, @@ -519,6 +554,14 @@ Internet-Draft MISP taxonomy format February 2017 "numerical_value": 30, "value": "30", "expanded": "30% Probably not", + + + +Dulaunoy & Iklody Expires October 12, 2017 [Page 10] + +Internet-Draft MISP taxonomy format April 2017 + + "description": "30% Probably not" }, { @@ -554,26 +597,163 @@ Internet-Draft MISP taxonomy format February 2017 "expanded": "Certainty of the elements mentioned in this Open Source Intelligence" } - - - -Dulaunoy & Iklody Expires August 17, 2017 [Page 10] - -Internet-Draft MISP taxonomy format February 2017 - - ] } -5. Acknowledgements +5. JSON Schema + + The JSON Schema [JSON-SCHEMA] below defines the structure of the MISP + taxonomy document as literally described before. The JSON Schema is + used validating a MISP taxonomy. The validation is a _MUST_ if the + taxonomy is included in the MISP taxonomies directory. + +{ + "required": [ + + + +Dulaunoy & Iklody Expires October 12, 2017 [Page 11] + +Internet-Draft MISP taxonomy format April 2017 + + + "namespace", + "description", + "version", + "predicates" + ], + "properties": { + "refs": { + "items": { + "type": "string" + }, + "uniqueItems": true, + "type": "array" + }, + "values": { + "items": { + "$ref": "#/defs/entry", + "type": "object" + }, + "uniqueItems": true, + "type": "array" + }, + "predicates": { + "items": { + "$ref": "#/defs/predicate", + "type": "object" + }, + "uniqueItems": true, + "type": "array" + }, + "version": { + "type": "integer" + }, + "description": { + "type": "string" + }, + "expanded": { + "type": "string" + }, + "namespace": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "defs": { + "required": [ + "predicate" + ], + + + +Dulaunoy & Iklody Expires October 12, 2017 [Page 12] + +Internet-Draft MISP taxonomy format April 2017 + + + "entry": { + "properties": { + "entry": { + "items": { + "required": [ + "value" + ], + "properties": { + "numerical_value": { + "type": "number" + }, + "expanded": { + "type": "string" + }, + "description": { + "type": "string" + }, + "value": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object" + }, + "uniqueItems": true, + "type": "array" + }, + "predicate": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object" + }, + "predicate": { + "required": [ + "value" + ], + "properties": { + "expanded": { + "type": "string" + }, + "numerical_value": { + "type": "number" + }, + "description": { + "type": "string" + }, + + + +Dulaunoy & Iklody Expires October 12, 2017 [Page 13] + +Internet-Draft MISP taxonomy format April 2017 + + + "colour": { + "type": "string" + }, + "value": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object" + } + }, + "id": "https://github.com/MISP/misp-taxonomies/blob/master/schema.json", + "title": "Validator for misp-taxonomies", + "$schema": "http://json-schema.org/schema#" +} + +6. Acknowledgements The authors wish to thank all the MISP community to support the creation of open standards in threat intelligence sharing. -6. References +7. References -6.1. Normative References +7.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, @@ -585,13 +765,27 @@ Internet-Draft MISP taxonomy format February 2017 DOI 10.17487/RFC4627, July 2006, . -6.2. Informative References +7.2. Informative References + + [JSON-SCHEMA] + "JSON Schema: A Media Type for Describing JSON Documents", + 2016, . [machine-tags] "Machine tags", 2007, . + + + + +Dulaunoy & Iklody Expires October 12, 2017 [Page 14] + +Internet-Draft MISP taxonomy format April 2017 + + [MISP-P] MISP, , "MISP Project - Malware Information Sharing Platform and Threat Sharing", . @@ -610,14 +804,6 @@ Authors' Addresses Email: alexandre.dulaunoy@circl.lu - - - -Dulaunoy & Iklody Expires August 17, 2017 [Page 11] - -Internet-Draft MISP taxonomy format February 2017 - - Andras Iklody Computer Incident Response Center Luxembourg 41, avenue de la gare @@ -651,22 +837,4 @@ Internet-Draft MISP taxonomy format February 2017 - - - - - - - - - - - - - - - - - - -Dulaunoy & Iklody Expires August 17, 2017 [Page 12] +Dulaunoy & Iklody Expires October 12, 2017 [Page 15]