From 5beea03ad2a95b30b5f612c30715469409936aa7 Mon Sep 17 00:00:00 2001 From: Alexandre Dulaunoy Date: Mon, 10 Oct 2016 07:52:21 +0200 Subject: [PATCH] Tag some clarification + highlight of MUST/SHOUD/SHALL --- misp-core-format/raw.md | 99 ++++++++++---------- misp-core-format/raw.md.txt | 174 ++++++++++++++++++++++++------------ 2 files changed, 167 insertions(+), 106 deletions(-) diff --git a/misp-core-format/raw.md b/misp-core-format/raw.md index a71291c..c88917a 100644 --- a/misp-core-format/raw.md +++ b/misp-core-format/raw.md @@ -79,30 +79,30 @@ analysis. The meaning of an event only depends of the information embedded in th #### uuid -uuid represents the Universally Unique IDentifier (UUID) [@!RFC4122] of the event. The uuid MUST be preserved -for any updates or transfer of the same event. UUID version 4 is RECOMMENDED when assigning it to a new event. +uuid represents the Universally Unique IDentifier (UUID) [@!RFC4122] of the event. The uuid **MUST** be preserved +for any updates or transfer of the same event. UUID version 4 is **RECOMMENDED** when assigning it to a new event. -uuid is represented as a JSON string. uuid MUST be present. +uuid is represented as a JSON string. uuid **MUST** be present. #### id id represents the human-readable identifier associated to the event for a specific MISP instance. -id is represented as a JSON string. id SHALL be present. +id is represented as a JSON string. id **SHALL** be present. #### published -published represents the event publication state. If the event was published, the published value MUST be true. -In any other publication state, the published value MUST be false. +published represents the event publication state. If the event was published, the published value **MUST** be true. +In any other publication state, the published value **MUST** be false. -published is represented as a JSON boolean. published MUST be present. +published is represented as a JSON boolean. published **MUST** be present. #### info info represents the information field of the event. info a free-text value to provide a human-readable summary -of the event. info SHOULD NOT be bigger than 256 characters. +of the event. info **SHOULD** NOT be bigger than 256 characters and **SHOULD** NOT include new-lines. -info is represented as a JSON string. info MUST be present. +info is represented as a JSON string. info **MUST** be present. #### threat_level_id @@ -120,9 +120,9 @@ threat_level_id represents the threat level. 3: : High -If a higher granularity is required, a MISP taxonomy applied as a Tag SHOULD be preferred. +If a higher granularity is required, a MISP taxonomy applied as a Tag **SHOULD** be preferred. -threat_level_id is represented as a JSON string. threat_level_id SHALL be present. +threat_level_id is represented as a JSON string. threat_level_id **SHALL** be present. #### date @@ -133,43 +133,43 @@ date is represented as a JSON string. #### timestamp -timestamp represents a reference time when the event, or one of the attributes within the event was created, or last updated/edited on the instance. timestamp is expressed in seconds (decimal) since 1st of January 1970 (Unix timestamp). The time zone MUST be UTC. +timestamp represents a reference time when the event, or one of the attributes within the event was created, or last updated/edited on the instance. timestamp is expressed in seconds (decimal) since 1st of January 1970 (Unix timestamp). The time zone **MUST** be UTC. -timestamp is represented as a JSON string. timestamp MUST be present. +timestamp is represented as a JSON string. timestamp **MUST** be present. #### publish_timestamp -publish_timestamp represents a reference time when the event was published on the instance. published_timestamp is expressed in seconds (decimal) since 1st of January 1970 (Unix timestamp). At each publication of an event, publish_timestamp MUST be updated. The time zone MUST be UTC. +publish_timestamp represents a reference time when the event was published on the instance. published_timestamp is expressed in seconds (decimal) since 1st of January 1970 (Unix timestamp). At each publication of an event, publish_timestamp **MUST** be updated. The time zone **MUST** be UTC. -publish_timestamp is represented as a JSON string. publish_timestamp MUST be present. +publish_timestamp is represented as a JSON string. publish_timestamp **MUST** be present. #### org_id org_id represents a human-readable identifier referencing an Org object of the organization which generated the event. -The org_id MUST be updated when the event is generated by a new instance. +The org_id **MUST** be updated when the event is generated by a new instance. -org_id is represented as a JSON string. org_id MUST be present. +org_id is represented as a JSON string. org_id **MUST** be present. #### orgc_id orgc_id represents a human-readable identifier referencing an Orgc object of the organization which created the event. -The orgc_id and Orc object MUST be preserved for any updates or transfer of the same event. +The orgc_id and Orc object **MUST** be preserved for any updates or transfer of the same event. -orgc_id is represented as a JSON string. orgc_id MUST be present. +orgc_id is represented as a JSON string. orgc_id **MUST** be present. #### attribute_count attribute_count represents the number of attributes in the event. attribute_count is expressed in decimal. -attribute_count is represented as a JSON string. attribute_count SHALL be present. +attribute_count is represented as a JSON string. attribute_count **SHALL** be present. #### distribution distribution represents the basic distribution rules of the event. The system must adhere to the distribution setting for access control and for dissemination of the event. -distribution is represented by a JSON string. distribution MUST be present and be one of the following options: +distribution is represented by a JSON string. distribution **MUST** be present and be one of the following options: 0 : Your Organisation Only @@ -190,7 +190,7 @@ distribution is represented by a JSON string. distribution MUST be present and b sharing\_group\_id represents a human-readable identifier referencing a Sharing Group object that defines the distribution of the event, if distribution level "4" is set. -sharing\_group\_id is represented by a JSON string and MUST be present. If a distribution level other than "4" is chosen the sharing\_group\_id MUST be set to "0". +sharing\_group\_id is represented by a JSON string and **MUST** be present. If a distribution level other than "4" is chosen the sharing\_group\_id **MUST** be set to "0". ## Objects @@ -200,12 +200,12 @@ sharing\_group\_id is represented by a JSON string and MUST be present. If a dis An Org object is composed of an uuid, name and id. The uuid represents the Universally Unique IDentifier (UUID) [@!RFC4122] of the organization. -The organization UUID is globally assigned to an organization and SHALL be kept overtime. +The organization UUID is globally assigned to an organization and **SHALL** be kept overtime. -The name is a readable description of the organization and SHOULD be present. +The name is a readable description of the organization and **SHOULD** be present. The id is a human-readable identifier generated by the instance and used as reference in the event. -uuid, name and id are represented as a JSON string. uuid, name and id MUST be present. +uuid, name and id are represented as a JSON string. uuid, name and id **MUST** be present. #### Sample Org Object @@ -221,20 +221,21 @@ uuid, name and id are represented as a JSON string. uuid, name and id MUST be pr An Orgc object is composed of an uuid, name and id. -The uuid MUST be preserved for any updates or transfer of the same event. UUID version 4 is RECOMMENDED when assigning it to a new event. -The organization UUID is globally assigned to an organization and SHALL be kept overtime. +The uuid **MUST** be preserved for any updates or transfer of the same event. UUID version 4 is **RECOMMENDED** when assigning it to a new event. +The organization UUID is globally assigned to an organization and **SHALL** be kept overtime. -The name is a readable description of the organization and SHOULD be present. +The name is a readable description of the organization and **SHOULD** be present. The id is a human-readable identifier generated by the instance and used as reference in the event. -uuid, name and id are represented as a JSON string. uuid, name and id MUST be present. - +uuid, name and id are represented as a JSON string. uuid, name and id **MUST** be present. ## Attribute Attributes are used to describe the indicators and contextual data of an event. The main information contained in an attribute is made up of a category-type-value triplet, where the category and type give meaning and context to the value. Through the various category-type combinations a wide range of information can be conveyed. +A MISP document **MUST** at least includes category-type-value triplet described in section "Attribute Attributes". + ### Sample Attribute Object ~~~~ @@ -260,22 +261,22 @@ where the category and type give meaning and context to the value. Through the v #### uuid -uuid represents the Universally Unique IDentifier (UUID) [@!RFC4122] of the event. The uuid MUST be preserved -for any updates or transfer of the same event. UUID version 4 is RECOMMENDED when assigning it to a new event. +uuid represents the Universally Unique IDentifier (UUID) [@!RFC4122] of the event. The uuid **MUST** be preserved +for any updates or transfer of the same event. UUID version 4 is **RECOMMENDED** when assigning it to a new event. -uuid is represented as a JSON string. uuid MUST be present. +uuid is represented as a JSON string. uuid **MUST** be present. #### id id represents the human-readable identifier associated to the event for a specific MISP instance. -id is represented as a JSON string. id SHALL be present. +id is represented as a JSON string. id **SHALL** be present. #### type type represents the means through which an attribute tries to describe the intent of the attribute creator, using a list of pre-defined attribute types. -type is represented as a JSON string. type MUST be present and it MUST be a valid selection for the chosen category. The list of valid category-type combinations is as follows: +type is represented as a JSON string. type **MUST** be present and it **MUST** be a valid selection for the chosen category. The list of valid category-type combinations is as follows: **Internal reference** : text, link, comment, other @@ -320,27 +321,27 @@ type is represented as a JSON string. type MUST be present and it MUST be a vali category represents the intent of what the attribute is describing as selected by the attribute creator, using a list of pre-defined attribute categories. -category is represented as a JSON string. category MUST be present and it MUST be a valid selection for the chosen type. The list of valid category-type combinations is mentioned above. +category is represented as a JSON string. category **MUST** be present and it **MUST** be a valid selection for the chosen type. The list of valid category-type combinations is mentioned above. #### to\_ids to\_ids represents whether the attribute is meant to be actionable. -to\_ids is represented as a JSON boolean. to\_ids MUST be present. +to\_ids is represented as a JSON boolean. to\_ids **MUST** be present. #### event\_id event\_id represents a human-readable identifier referencing the Event object that the attribute belongs to. -The event\_id SHOULD be updated when the event is imported to reflect the newly created event's id on the instance. +The event\_id **SHOULD** be updated when the event is imported to reflect the newly created event's id on the instance. -event\_id is represented as a JSON string. event\_id MUST be present. +event\_id is represented as a JSON string. event\_id **MUST** be present. #### distribution distribution represents the basic distribution rules of the attribute. The system must adhere to the distribution setting for access control and for dissemination of the attribute. -distribution is represented by a JSON string. distribution MUST be present and be one of the following options: +distribution is represented by a JSON string. distribution **MUST** be present and be one of the following options: 0 : Your Organisation Only @@ -362,38 +363,42 @@ distribution is represented by a JSON string. distribution MUST be present and b #### timestamp -timestamp represents a reference time when the attribute was created or last modified. timestamp is expressed in seconds (decimal) since 1st of January 1970 (Unix timestamp). The time zone MUST be UTC. +timestamp represents a reference time when the attribute was created or last modified. timestamp is expressed in seconds (decimal) since 1st of January 1970 (Unix timestamp). The time zone **MUST** be UTC. -timestamp is represented as a JSON string. timestamp MUST be present. +timestamp is represented as a JSON string. timestamp **MUST** be present. #### comment -comment is a contextual comment field. +comment is a contextual comment field. -comment is represented by a JSON string. comment MAY be present. +comment is represented by a JSON string. comment **MAY** be present. #### sharing_group_id sharing\_group\_id represents a human-readable identifier referencing a Sharing Group object that defines the distribution of the attribute, if distribution level "4" is set. -sharing\_group\_id is represented by a JSON string and MUST be present. If a distribution level other than "4" is chosen the sharing\_group\_id MUST be set to "0". +sharing\_group\_id is represented by a JSON string and **MUST** be present. If a distribution level other than "4" is chosen the sharing\_group\_id **MUST** be set to "0". #### deleted deleted represents a setting that allows attributes to be revoked. Revoked attributes are not actionable and exist merely to inform other instances of a revocation. -deleted is represented by a JSON boolean. deleted MUST be present. +deleted is represented by a JSON boolean. deleted **MUST** be present. #### value value represents the payload of an attribute. The format of the value is dependent on the type of the attribute. -value is represented by a JSON string. value MUST be present. +value is represented by a JSON string. value **MUST** be present. ## Tag A Tag is a simple method to classify an event with a simple tag name. The tag name can be freely chosen. The tag name can be also chosen from a fixed machine-tag vocabulary called MISP taxonomies[[@?MISP-T]]. A Tag is represented as a JSON array where each element describes each tag associated. A Tag array SHALL be, at least, at Event level. A tag element is described with a name, id, colour, exportable flag and org_id. +exportable represents a setting if the tag is kept local or exportable to other MISP instances. exportable is represented by a JSON boolean. + +name **MUST** be present. exportable **SHALL** be present. + ### Sample Tag ~~~~ diff --git a/misp-core-format/raw.md.txt b/misp-core-format/raw.md.txt index 1a0eafd..bec95c3 100644 --- a/misp-core-format/raw.md.txt +++ b/misp-core-format/raw.md.txt @@ -78,9 +78,9 @@ Table of Contents 2.4.2. Attribute Attributes . . . . . . . . . . . . . . . . 8 2.5. Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.5.1. Sample Tag . . . . . . . . . . . . . . . . . . . . . 12 - 3. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 12 - 4. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 - 4.1. Normative References . . . . . . . . . . . . . . . . . . 12 + 3. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13 + 4. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 + 4.1. Normative References . . . . . . . . . . . . . . . . . . 13 4.2. Informative References . . . . . . . . . . . . . . . . . 13 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 @@ -174,7 +174,7 @@ Internet-Draft MISP core format October 2016 info represents the information field of the event. info a free-text value to provide a human-readable summary of the event. info SHOULD - NOT be bigger than 256 characters. + NOT be bigger than 256 characters and SHOULD NOT include new-lines. info is represented as a JSON string. info MUST be present. @@ -368,8 +368,32 @@ Internet-Draft MISP core format October 2016 meaning and context to the value. Through the various category-type combinations a wide range of information can be conveyed. + A MISP document MUST at least includes category-type-value triplet + described in section "Attribute Attributes". + 2.4.1. Sample Attribute Object + + + + + + + + + + + + + + + + +Dulaunoy & Iklody Expires April 4, 2017 [Page 7] + +Internet-Draft MISP core format October 2016 + + "Attribute": { "id": "346056", "type": "comment", @@ -387,13 +411,6 @@ Internet-Draft MISP core format October 2016 "ShadowAttribute": [] } - - -Dulaunoy & Iklody Expires April 4, 2017 [Page 7] - -Internet-Draft MISP core format October 2016 - - 2.4.2. Attribute Attributes 2.4.2.1. uuid @@ -425,6 +442,14 @@ Internet-Draft MISP core format October 2016 Internal reference text, link, comment, other + + + +Dulaunoy & Iklody Expires April 4, 2017 [Page 8] + +Internet-Draft MISP core format October 2016 + + Targeting data target-user, target-email, target-machine, target-org, target- location, target-external, comment @@ -441,15 +466,6 @@ Internet-Draft MISP core format October 2016 filename|tlsh, filename|imphash, filename|pehash, ip-src, ip-dst, hostname, domain, email-src, email-dst, email-subject, email- attachment, url, user-agent, AS, pattern-in-file, pattern-in- - - - - -Dulaunoy & Iklody Expires April 4, 2017 [Page 8] - -Internet-Draft MISP core format October 2016 - - traffic, yara, attachment, malware-sample, link, malware-type, comment, text, vulnerability, x509-fingerprint-sha1, other @@ -480,6 +496,16 @@ Internet-Draft MISP core format October 2016 filename, regkey, regkey|value, comment, text, other Network activity + + + + + +Dulaunoy & Iklody Expires April 4, 2017 [Page 9] + +Internet-Draft MISP core format October 2016 + + ip-src, ip-dst, hostname, domain, domain|ip, email-dst, url, uri, user-agent, http-method, AS, snort, pattern-in-file, pattern-in- traffic, attachment, comment, text, x509-fingerprint-sha1, other @@ -499,13 +525,6 @@ Internet-Draft MISP core format October 2016 pattern-in-traffic, pattern-in-memory, vulnerability, attachment, malware-sample, link, comment, text, x509-fingerprint-sha1, other - - -Dulaunoy & Iklody Expires April 4, 2017 [Page 9] - -Internet-Draft MISP core format October 2016 - - Financial fraud btc, iban, bic, bank-account-nr, aba-rtn, bin, cc-number, prtn, comment, text, other @@ -534,6 +553,15 @@ Internet-Draft MISP core format October 2016 event_id represents a human-readable identifier referencing the Event object that the attribute belongs to. + + + + +Dulaunoy & Iklody Expires April 4, 2017 [Page 10] + +Internet-Draft MISP core format October 2016 + + The event_id SHOULD be updated when the event is imported to reflect the newly created event's id on the instance. @@ -554,14 +582,6 @@ Internet-Draft MISP core format October 2016 1 This Community Only - - - -Dulaunoy & Iklody Expires April 4, 2017 [Page 10] - -Internet-Draft MISP core format October 2016 - - 2 Connected Communities @@ -588,6 +608,16 @@ Internet-Draft MISP core format October 2016 comment is represented by a JSON string. comment MAY be present. + + + + + +Dulaunoy & Iklody Expires April 4, 2017 [Page 11] + +Internet-Draft MISP core format October 2016 + + 2.4.2.10. sharing_group_id sharing_group_id represents a human-readable identifier referencing a @@ -606,18 +636,6 @@ Internet-Draft MISP core format October 2016 deleted is represented by a JSON boolean. deleted MUST be present. - - - - - - - -Dulaunoy & Iklody Expires April 4, 2017 [Page 11] - -Internet-Draft MISP core format October 2016 - - 2.4.2.12. value value represents the payload of an attribute. The format of the @@ -635,8 +653,27 @@ Internet-Draft MISP core format October 2016 A tag element is described with a name, id, colour, exportable flag and org_id. + exportable represents a setting if the tag is kept local or + exportable to other MISP instances. exportable is represented by a + JSON boolean. + + name MUST be present. exportable SHALL be present. + 2.5.1. Sample Tag + + + + + + + + +Dulaunoy & Iklody Expires April 4, 2017 [Page 12] + +Internet-Draft MISP core format October 2016 + + "Tag": [{ "org_id": "0", "exportable": true, @@ -663,17 +700,6 @@ Internet-Draft MISP core format October 2016 DOI 10.17487/RFC4122, July 2005, . - - - - - - -Dulaunoy & Iklody Expires April 4, 2017 [Page 12] - -Internet-Draft MISP core format October 2016 - - [RFC4627] Crockford, D., "The application/json Media Type for JavaScript Object Notation (JSON)", RFC 4627, DOI 10.17487/RFC4627, July 2006, @@ -689,6 +715,21 @@ Internet-Draft MISP core format October 2016 Authors' Addresses + + + + + + + + + + +Dulaunoy & Iklody Expires April 4, 2017 [Page 13] + +Internet-Draft MISP core format October 2016 + + Alexandre Dulaunoy Computer Incident Response Center Luxembourg 41, avenue de la gare @@ -725,4 +766,19 @@ Authors' Addresses -Dulaunoy & Iklody Expires April 4, 2017 [Page 13] + + + + + + + + + + + + + + + +Dulaunoy & Iklody Expires April 4, 2017 [Page 14]