MISP
/
misp-rfc
mirror of https://github.com/MISP/misp-rfc
2
0
Fork 0
Code Issues Releases Wiki Activity

JSON Schema added

pull/6/head
Alexandre Dulaunoy 2017-04-11 09:00:44 +02:00
parent 047f920a9b
commit 088eff88f8
1 changed files with 294 additions and 126 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

420
misp-taxonomy-format/raw.md.txt
View File

@ -5,7 +5,7 @@
Network Working Group A. Dulaunoy Network Working Group A. Dulaunoy
Internet-Draft A. Iklody Internet-Draft A. Iklody
Intended status: Informational CIRCL Intended status: Informational CIRCL
Expires: August 17, 2017 February 13, 2017 Expires: October 12, 2017 April 10, 2017
MISP taxonomy format MISP taxonomy format
@ -16,7 +16,9 @@ Abstract
This document describes the MISP taxonomy format which describes a This document describes the MISP taxonomy format which describes a
simple JSON format to represent machine tags (also called triple simple JSON format to represent machine tags (also called triple
tags) vocabularies. A public directory of common vocabularies MISP 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 Status of This Memo
@ -33,7 +35,7 @@ Status of This Memo
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." 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 Copyright Notice
@ -47,39 +49,41 @@ Copyright Notice
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of 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 the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Dulaunoy & Iklody Expires August 17, 2017 [Page 1]
Internet-Draft MISP taxonomy format February 2017
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Conventions and Terminology . . . . . . . . . . . . . . . 3 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 3
2. Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 3 2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2. predicates . . . . . . . . . . . . . . . . . . . . . . . 3 2.2. predicates . . . . . . . . . . . . . . . . . . . . . . . 4
2.3. values . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.3. values . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.4. optional fields . . . . . . . . . . . . . . . . . . . . . 4 2.4. optional fields . . . . . . . . . . . . . . . . . . . . . 4
2.4.1. colour . . . . . . . . . . . . . . . . . . . . . . . 4 2.4.1. colour . . . . . . . . . . . . . . . . . . . . . . . 4
2.4.2. description . . . . . . . . . . . . . . . . . . . . . 4 2.4.2. description . . . . . . . . . . . . . . . . . . . . . 5
2.4.3. numerical_value . . . . . . . . . . . . . . . . . . . 5 2.4.3. numerical_value . . . . . . . . . . . . . . . . . . . 5
3. Directory . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3. Directory . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.1. Sample Manifest . . . . . . . . . . . . . . . . . . . . . 6 3.1. Sample Manifest . . . . . . . . . . . . . . . . . . . . . 7
4. Sample Taxonomy in MISP taxonomy format . . . . . . . . . . . 6 4. Sample Taxonomy in MISP taxonomy format . . . . . . . . . . . 7
4.1. Admiralty Scale Taxonomy . . . . . . . . . . . . . . . . 6 4.1. Admiralty Scale Taxonomy . . . . . . . . . . . . . . . . 7
4.2. Open Source Intelligence - Classification . . . . . . . . 8 4.2. Open Source Intelligence - Classification . . . . . . . . 9
5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 5. JSON Schema . . . . . . . . . . . . . . . . . . . . . . . . . 11
6. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 14
6.1. Normative References . . . . . . . . . . . . . . . . . . 11 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 14
6.2. Informative References . . . . . . . . . . . . . . . . . 11 7.1. Normative References . . . . . . . . . . . . . . . . . . 14
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 7.2. Informative References . . . . . . . . . . . . . . . . . 14
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15
1. Introduction 1. Introduction
@ -102,18 +106,17 @@ Table of Contents
In the MISP taxonomy context, machine tags help analysts to classify In the MISP taxonomy context, machine tags help analysts to classify
their cybersecurity events, indicators or threats. MISP taxonomies their cybersecurity events, indicators or threats. MISP taxonomies
can be used for classification, filtering, triggering actions or 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 visualisation depending on their use in threat intelligence platforms
such as MISP [MISP-P]. 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 1.1. Conventions and Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 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 values defines all the values for each predicate in the namespace
defined. values SHOULD be present. defined. values SHOULD be present.
Dulaunoy & Iklody Expires October 12, 2017 [Page 3]
Internet-Draft MISP taxonomy format April 2017
2.2. predicates 2.2. predicates
The predicates array contains one or more JSON objects which lists 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 value and expanded. value MUST be present. expanded SHOULD be
present. value is represented as a string and describes the predicate present. value is represented as a string and describes the predicate
value. The predicate value MUST not contain spaces or colons. 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 expanded is represented as a string and describes the human-readable
version of the predicate value. version of the predicate value.
@ -212,20 +219,19 @@ Internet-Draft MISP taxonomy format February 2017
"value": "amber" "value": "amber"
}...] }...]
Dulaunoy & Iklody Expires October 12, 2017 [Page 4]
Internet-Draft MISP taxonomy format April 2017
2.4.2. description 2.4.2. description
description fields MAY be used at predicates or values level to add a description fields MAY be used at predicates or values level to add a
descriptive and human-readable information about the specific descriptive and human-readable information about the specific
predicate or value. The field is represented as a string. predicate or value. The field is represented as a string.
Implementations MAY use the description field to improve more 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 contextual information. The description at the namespace level is a
MUST as described above. 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: 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", "predicate": "confidence-level",
"entry": [ "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 3. Directory
The MISP taxonomies directory is publicly available [MISP-T] in a git 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 describes the taxonomy available with the description, name and
version field. version field.
Dulaunoy & Iklody Expires October 12, 2017 [Page 6]
Internet-Draft MISP taxonomy format April 2017
3.1. Sample Manifest 3.1. Sample Manifest
{ {
@ -330,14 +373,6 @@ Internet-Draft MISP taxonomy format February 2017
"version": 1, "version": 1,
"predicates": [ "predicates": [
{ {
Dulaunoy & Iklody Expires August 17, 2017 [Page 6]
Internet-Draft MISP taxonomy format February 2017
"value": "source-reliability", "value": "source-reliability",
"expanded": "Source Reliability" "expanded": "Source Reliability"
}, },
@ -351,6 +386,14 @@ Internet-Draft MISP taxonomy format February 2017
"predicate": "source-reliability", "predicate": "source-reliability",
"entry": [ "entry": [
{ {
Dulaunoy & Iklody Expires October 12, 2017 [Page 7]
Internet-Draft MISP taxonomy format April 2017
"value": "a", "value": "a",
"expanded": "Completely reliable" "expanded": "Completely reliable"
}, },
@ -386,14 +429,6 @@ Internet-Draft MISP taxonomy format February 2017
{ {
"value": "2", "value": "2",
"expanded": "Probably true" "expanded": "Probably true"
Dulaunoy & Iklody Expires August 17, 2017 [Page 7]
Internet-Draft MISP taxonomy format February 2017
}, },
{ {
"value": "3", "value": "3",
@ -407,6 +442,14 @@ Internet-Draft MISP taxonomy format February 2017
"value": "5", "value": "5",
"expanded": "Improbable" "expanded": "Improbable"
}, },
Dulaunoy & Iklody Expires October 12, 2017 [Page 8]
Internet-Draft MISP taxonomy format April 2017
{ {
"value": "6", "value": "6",
"expanded": "Truth cannot be judged" "expanded": "Truth cannot be judged"
@ -442,14 +485,6 @@ Internet-Draft MISP taxonomy format February 2017
"expanded": "Electronic forum", "expanded": "Electronic forum",
"value": "electronic-forum" "value": "electronic-forum"
}, },
Dulaunoy & Iklody Expires August 17, 2017 [Page 8]
Internet-Draft MISP taxonomy format February 2017
{ {
"expanded": "Mailing-list", "expanded": "Mailing-list",
"value": "mailing-list" "value": "mailing-list"
@ -463,6 +498,14 @@ Internet-Draft MISP taxonomy format February 2017
"value": "expansion" "value": "expansion"
} }
], ],
Dulaunoy & Iklody Expires October 12, 2017 [Page 9]
Internet-Draft MISP taxonomy format April 2017
"predicate": "source-type" "predicate": "source-type"
}, },
{ {
@ -498,14 +541,6 @@ Internet-Draft MISP taxonomy format February 2017
{ {
"numerical_value": 75, "numerical_value": 75,
"value": "75", "value": "75",
Dulaunoy & Iklody Expires August 17, 2017 [Page 9]
Internet-Draft MISP taxonomy format February 2017
"expanded": "75% Probable", "expanded": "75% Probable",
"description": "75% Probable" "description": "75% Probable"
}, },
@ -519,6 +554,14 @@ Internet-Draft MISP taxonomy format February 2017
"numerical_value": 30, "numerical_value": 30,
"value": "30", "value": "30",
"expanded": "30% Probably not", "expanded": "30% Probably not",
Dulaunoy & Iklody Expires October 12, 2017 [Page 10]
Internet-Draft MISP taxonomy format April 2017
"description": "30% Probably not" "description": "30% Probably not"
}, },
{ {
@ -554,26 +597,163 @@ Internet-Draft MISP taxonomy format February 2017
"expanded": "Certainty of the elements mentioned "expanded": "Certainty of the elements mentioned
in this Open Source Intelligence" 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 The authors wish to thank all the MISP community to support the
creation of open standards in threat intelligence sharing. 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 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
@ -585,13 +765,27 @@ Internet-Draft MISP taxonomy format February 2017
DOI 10.17487/RFC4627, July 2006, DOI 10.17487/RFC4627, July 2006,
<http://www.rfc-editor.org/info/rfc4627>. <http://www.rfc-editor.org/info/rfc4627>.
6.2. Informative References 7.2. Informative References
[JSON-SCHEMA]
"JSON Schema: A Media Type for Describing JSON Documents",
2016, <https://tools.ietf.org/html/draft-wright-json-
schema>.
[machine-tags] [machine-tags]
"Machine tags", 2007, "Machine tags", 2007,
<https://www.flickr.com/groups/51035612836@N01/ <https://www.flickr.com/groups/51035612836@N01/
discuss/72157594497877875/>. discuss/72157594497877875/>.
Dulaunoy & Iklody Expires October 12, 2017 [Page 14]
Internet-Draft MISP taxonomy format April 2017
[MISP-P] MISP, , "MISP Project - Malware Information Sharing [MISP-P] MISP, , "MISP Project - Malware Information Sharing
Platform and Threat Sharing", <https://github.com/MISP>. Platform and Threat Sharing", <https://github.com/MISP>.
@ -610,14 +804,6 @@ Authors' Addresses
Email: alexandre.dulaunoy@circl.lu Email: alexandre.dulaunoy@circl.lu
Dulaunoy & Iklody Expires August 17, 2017 [Page 11]
Internet-Draft MISP taxonomy format February 2017
Andras Iklody Andras Iklody
Computer Incident Response Center Luxembourg Computer Incident Response Center Luxembourg
41, avenue de la gare 41, avenue de la gare
@ -651,22 +837,4 @@ Internet-Draft MISP taxonomy format February 2017
Dulaunoy & Iklody Expires October 12, 2017 [Page 15]
Dulaunoy & Iklody Expires August 17, 2017 [Page 12]