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
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,
<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", 2007,
<https://www.flickr.com/groups/51035612836@N01/
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
Platform and Threat Sharing", <https://github.com/MISP>.
@ -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]