Information Exchange Policy 2.0 JSON Specification

Available in PDF

1. Introduction

1.1 Purpose

Automating the exchange of security and threat information in a timely manner is crucial to the future and effectiveness of the security response community. The timely distribution of sensitive information will only thrive in an environment where both producers and consumers have a clear understanding of how shared information can and cannot be used, with very few variations of interpretation.

The general lack of adequate policy that supports information exchange is increasingly becoming an impediment to timely sharing. This will only be exacerbated as more organizations start actively participating in information exchange communities and the volume of security and threat information being shared continues to grow.

The Traffic Light Protocol (TLP) is the most commonly used method to mark and protect information that is shared. The original intent behind TLP was to speed up the time-to-action on shared information by pre-declaring the permitted redistribution of that information, reducing the need for everyone to ask the producer if it could be "shared with XYZ in my organization" and for that purpose TLP still works.

The challenge for producers of information is that they need to be able to convey more than just the permitted redistribution of the information. There can be a lack of clarity when defining and interpreting the permitted actions and uses of information shared between organizations. This is compounded by the sensitive nature and commercially competitive aspects of security and threat information.

FIRST, interested in enabling the global development and maturation of CSIRTs, recognized that the general lack of adequate policy supporting information exchange is increasingly becoming an impediment to information sharing amongst CSIRT teams.

The FIRST IEP Special Interest Group (IEP-SIG) was formed to develop, oversee and grow the IEP Framework and to ensure it met the needs of the community.

1.2 Requirements

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 RFC2119 (Key words for use in RFCs to Indicate Requirement Levels)1.

An implementation is not compliant if it fails to satisfy one or more of the MUST or REQUIRED level requirements for the protocols it implements. An implementation that satisfies all the MUST or REQUIRED level and all the SHOULD level requirements for its protocols is said to be "unconditionally compliant"; one that satisfies all the MUST level requirements but not all the SHOULD level requirements for its protocols is said to be "conditionally compliant."

1.3 Terminology

2. Architecture

The IEP Framework is designed to be succinct, flexible and descriptive. It tries to help producers describe to consumers exactly what they can and can’t do with the information that they receive.

The IEP Framework is built from a series of structures that work together to convey the Providers intent.

The Providers intent is documented by an Information Exchange Policy (IEP). The IEP is constructed from a series of Policy Statements that together form an IEP.

An IEP can be created as a standalone IEP Policy File (allowing that file to be referenced from elsewhere), or the IEP can be embedded within another protocol structure such as the STIX Threat Intelligence Sharing Protocol. This difference is shown below in Figure 1 - Embedded vs Referenced.

  Embedded vs Referenced
Figure 1: Embedded vs Referenced

An IEP Policy File MUST contain at least one IEP, but MAY contain multiple IEP’s. Each IEP Policy MUST have a unique Policy ID.

A Policy Reference contains a URL and a Policy ID that refers to a particular IEP Policy housed within an Internet accessible IEP Policy File. Policy References are designed to be used within other information sharing standards and protocols to enable easy reuse of common Information Exchange Policies.

3. JSON IEP Format

The JSON IEP format uses the JSON text format for the serializations of structured data as defined in RFC7159 (The JavaScript Object Notation (JSON) Data Interchange Format)2.

In addition, the IEP Policy Statements naming convention follows the same conventions as described in the STIX Version 2.1 WD05 standard. The STIX 2.1 standard states that all property names use words separated by underscores ( _ ), and all property values that use a mandated vocabulary should be lowercase and separated by hyphens ( - ). This IEP JSON standard follows the same naming structure for its JSON name / value pairs to retain maximum compatibility with JSON and the STIX standard.

4. IEP Information

Further information about the IEP 2.0 Framework can be found within the FIRST IEP 2.0 Framework document available on the first.org website.

4.1 IEP Structure

A JSON IEP MUST be defined as a single JSON Object.

Each JSON IEP JSON Object MUST contain all of the IEP Policy Statements as defined in the list below. The mandatory policy statements in IEP Framework 2.0 are:

4.2 Using an IEP

As mentioned earlier an IEP is defined using an IEP JSON Object. This IEP JSON Object can be used in one of two ways:

More information about the difference between embedded and referenced IEP Policies can be found in section 8.3.

4.3 Immutability and versioning IEPs

You cannot update an IEP once it has been applied or associated with a piece of information. IEPs are immutable once they have been associated or applied to a piece of information. If a Producer wishes to change any value within an IEP then a new IEP MUST be created under a new Policy ID, and the new IEP used instead.

4.4 Caching IEPs

A Recipient SHOULD keep a cached copy of all IEPs that mark information stored within its information repository, so that all information marked with IEPs will have a corresponding IEP locally available.

A Recipient MAY keep a cached copy of all IEPs that mark information not currently stored within its information repository if it so chooses.

4.5 IEP Violations

A Protocol Author can choose to enforce consequences for violation of IEP within their Protocol, or it can choose to make IEP informational only and not enforce restrictions for violation of the IEP. This is a decision the Protocol Author needs to make and document within their Protocol.

If IEP violations result in consequences when used within a Protocol, we recommend that Protocol Authors document those consequences in detail within their Protocol documentation. It is important that Protocol Authors describe the consequences of IEP policy violations in enough detail that implementers of the Protocol can clearly understand how to handle IEP policy violations.

5. IEP Policy Statements

Each IEP Policy Statement MUST be a JSON name/value pair, where the name is a string, and it is separated from the value by a colon.

All IEP Policy Statement names use lowercase words separated by underscores ( _ ), and all IEP Policy Statement values that are policy enumeration strings (i.e. they are part of a list that users can select from) are lowercase and separated by hyphens ( - ).

An example IEP Policy Statement for the encrypt_in_transit Policy Statement is shown below:

"encrypt_in_transit": "may"

5.1 id

The id statement is used to identify the IEP, and to allow the IEP to be referenced from other protocols and standards. The id statement MUST be included in an IEP. The id statement name MUST be the JSON string "id", and it must be in lowercase. The id statement value MUST be a JSON string containing a UUIDv4 or UUIDv5 identifier as defined in RFC4122 (A Universally Unique IDentifier (UUID) URN Namespace)3.

5.2 name

The name statement is a human readable name for the IEP. The name statement MUST be included in an IEP. The name statement name MUST be the JSON string "name", and it must be in lowercase. The name statement value MAY be written in any language. The name statement value MUST be a JSON string, and MUST contain at least one non-whitespace character.

5.3 description

The description statement is a human readable description of the IEP. The description statement MUST be included in an IEP. The description statement name MUST be the JSON string "description", and it must be in lowercase. The description statement value MAY be written in any language. The description statement value MUST be a JSON string, but MAY be an empty string.

The description MUST NOT be used to add any additional conditions to the IEP.

5.4 iep_version

The iep_version statement describes which version of the Information Exchange Policy framework that the IEP adheres to. The iep_version statement MUST be included in an IEP. The iep_version statement name MUST be the JSON string "iep_version", and it must be in lowercase. The iep_version statement value MUST be the JSON number "2.0" (without the quotes).

5.5 start_date

The start_date statement describes when the IEP begins to apply to information that references the IEP.

The start_date statement MUST be included in an IEP. The start_date statement name MUST be the JSON string "start_date", and it must be in lowercase. The start_date statement value MUST be a JSON string containing the start date in Co-ordinated Universal Time (UTC) as per RFC3339 (Date and Time on the Internet: Timestamps)4.

5.6 end_date

The end_date statement describes when the IEP ceases to apply to information that references the IEP.

The end_date statement MUST be included in an IEP. The end date statement name MUST be the JSON string "end_date", and it must be in lowercase. The end_date statement value MUST either be a JSON string containing the end date in Co-ordinated Universal Time (UTC) as per RFC3339 (Date and Time on the Internet: Timestamps)4, or the JSON literal null value null. null MUST be used as the end_date statement value when the producer wishes the IEP to apply to the information forever.

5.7 encrypt_in_transit

The encrypt_in_transit statement is used to inform the recipient whether the received information has to be encrypted when it is retransmitted by the recipient.

The encrypt_in_transit statement MUST be included in an IEP. The encrypt_in_transit statement name MUST be the JSON string "encrypt_in_transit", and it must be in lowercase.

The encrypt_in_transit statement value MUST be a JSON string, and MUST be set to one of the following two Policy Enumeration strings:

As the encrypt_in_transit statement value is a policy enumeration string, it MUST be lowercase.

5.8 permitted_actions

The permitted_actions statement is used to inform a recipient organization of the actions they may take with the information they receive, based on how visible those actions would be to a third-party.

The permitted_actions statement MUST be included in an IEP. The permitted_actions statement name MUST be the JSON string "permitted_actions", and it must be in lowercase.

The permitted_actions statement value MUST be a JSON string, and MUST be set to one of the following five Policy Enumeration strings:

As the permitted_actions statement value is a policy enumeration string, it MUST be lowercase.

If the permitted actions statement value is set to "none", then the recipient MUST NOT perform any actions based on the information they received. We do not recommend this value is selected.

If the permitted actions statement value is set to "contact-for-instruction", then the recipient MUST contact the information creator and seek permission if they wish to perform any actions based on the information they received.

If the permitted actions statement value is set to "internally-visible-actions", then the recipient MAY conduct actions on the information received that are only visible on the Recipient's internal networks and systems, and MUST NOT conduct actions that are visible outside of the Recipients networks and systems or that are visible to third parties., e.g. the recipient can perform a search within their own proxy server logs.

If the permitted actions statement value is set to "externally-visible-indirect-actions", then the recipients MAY conduct internally visible actions, and MAY also conduct indirect, or passive, actions on the information received. Recipients MUST NOT conduct direct, or active, actions that will be visible by Threat Actors mentioned within the shared information, e.g. the recipient can perform an Internet Archive search for a website, but should not visit the website directly.

If the permitted actions statement value is set to "externally-visible-direct-actions", then the recipient MAY perform any actions based on the information they received e.g. the recipient can connect directly to a website.

5.9 affected_party_notifications

The affected_party_notifications statement is used to tell the recipient if they may contact parties who are affected by the information received by the recipient.

PLEASE NOTE: Setting this Policy Statement to "may" does not allow the recipient to forward full copies of the information received directly to the affected party, but it instead allows the recipient to contact the affected party via any means and inform them of the parts of the information that directly affects the affected party. Please see section 9.2 of the Information Exchange Policy 2.0 Framework Definition document for more information.

PLEASE NOTE: The sharing restrictions set by the tlp Policy Statement can be overridden by the setting of the affected_party_notifications Policy Statement in some situations. Please see section 9.2 of the Information Exchange Policy 2.0 Framework Definition document for more information.

The affected_party_notifications statement MUST be included in an IEP. The affected_party_notifications statement name MUST be the JSON string "affected_party_notifications", and it must be lowercase.

The affected_party_notifications statement value MUST be a JSON string, and MUST be set to one of the following two Policy Enumeration strings:

As the affected_party_notifications statement value is a policy enumeration string, it MUST be lowercase.

If the affected_party_notifications statement value is set to "may", then the recipient MAY contact parties who are affected by the information received by the recipient. Note - this does not allow the recipient to forward the information directly to the affected party, but it instead allows the recipient to contact the affected party and tell them the part of the information that affects them.

If the affected_party_notifications statement value is set to "must-not", then the recipient MUST NOT contact any affected parties in regard to the information they received. In some cases, an affected party may be a member of the sharing community that received the original information. If this is the case then the tlp setting takes precedence, and the affected party may be treated as a community member rather than as an affected party.

Please note that in some cases the recipient is required to report the information to law enforcement or other officials due to laws in their local jurisdiction, and those laws will take precedence over this IEP Policy Statement.

5.10 tlp

The tlp statement is used to inform the recipient with whom they may re-share copies of the information. IEP uses the FIRST TLP-SIG definition of TLP4.

PLEASE NOTE: The sharing restrictions set by the tlp Policy Statement can be overridden by the setting of the affected_party_notifications Policy Statement in some situations. Please see section 9.2 of the Information Exchange Policy 2.0 Framework Definition document for more information.

The tlp statement MUST be included in an IEP. The tlp statement name MUST be the JSON string "tlp", and it must be in lowercase.

The tlp statement value MUST be a JSON string, and MUST be set to one of the following four Policy Enumeration strings:

As the tlp statement value is a policy enumeration string, it MUST be lowercase.

5.11 attribution

The attribution statement allows the provider to communicate whether or not it wants to be attributed as the producer of the information when the information is redistributed by the recipient.

The attribution statement MUST be included in an IEP. The attribution statement name MUST be the JSON string "attribution", and it must be in lowercase.

The attribution statement value MUST be a JSON string, and MUST be set to one of the following three Policy Enumeration strings:

As the attribution statement value is a policy enumeration string, it MUST be lowercase.

If the attribution statement value is set to "must", then the recipient MUST ensure that any information that refers to the IEP MUST maintain attribution of the information to the producer when the information is re-shared.

If the attribution statement value is set to "must-not", then the recipient MUST ensure that any information re-shared MUST NOT attribute the information to the producer in any way when the information is re-shared. Warning: It still may be possible attribution will still be derived from the information itself.

If the attribution statement value is set to "may", then it is up to the recipient if they wish to attribute the information to the producer when the information is re-shared.

5.12 unmodified_resale

The unmodified_resale statement allows the provider to communicate if the consumer is permitted to resell the information they receive from the producer within their own product offerings in an unmodified state or one that is semantically equivalent. Semantically equivalent in this context means transposing the data from one format to another i.e. transposing the information from a CSV file format to a JSON file format would be considered semantically equivalent.

The unmodified_resale statement MUST be a JSON name/value pair. The unmodified_resale statement MUST be included in an IEP. The unmodified_resale statement name MUST be the JSON string "unmodified_resale", and it must be in lowercase.

The unmodified_resale statement value MUST be a JSON string, and MUST be set to one of the following two Policy Enumeration strings:

As the unmodified_resale statement value is a policy enumeration string, it MUST be lowercase.

If the unmodified_resale statement value is set to "may", then it the consumer MAY sell the information they receive in an unmodified (or semantically equivalent format) without restriction.

If the unmodified_resale statement value is set to "must-not", then the recipient MUST NOT sell or resell any information that refers to the IEP in an unmodified (or semantically equivalent format).

PLEASE NOTE: Setting the unmodified_resale statement value to "must-not" does not restrict the consumer from deriving their own information from the information provided by the producer, and then selling their own derived information.

5.13 external_references

The external_references statement allows the provider to provide a list of URLs that provide further human readable information about the policy described in the IEP. This allows a provider to provide more context about the IEP and to document why the certain IEP Policy Statement values were selected, and what the IEP was developed to control.

The external_references statement MUST be included in an IEP. The external_references statement name MUST be the JSON string "external_references", and it must be in lowercase.

The external_references statement value MUST be a JSON array. The JSON array MAY either be an empty array, or an array of JSON strings containing valid URLs as defined in RFC3986 (Uniform Resource Identifier (URI): Generic Syntax)5.

6. IEP Example

The following is an example of a complete IEP JSON Object:

{
"id": "5945e5d4-b66d-40ad-9aec-cfadbcac961c",
    "name": "My IEP Policy #1",
    "description": "This is my first IEP Policy.",
    "iep_version": 2.0,
    "start_date": "2017-01-01T00:00:00Z",
    "end_date": null,
    "encrypt_in_transit": "must",
    "permitted_actions": "internally-visible-direct-actions",
    "affected_party_notifications": "must-not",
    "tlp": "red",
    "attribution": "must-not",
    "unmodified_resale": "must-not",
    "external_references": [ 
        "https://www.first.org/tlp", 
        "https://www.first.org/iep"
    ]
}

7. IEP Policy File

7.1 IEP Policy File Structure

A JSON IEP Policy file MUST contain at least one IEP within it. A JSON IEP file MAY contain multiple IEPs within it if desired. A JSON IEP Policy file MUST NOT contain any other JSON structure other than one or more IEPs.

If the JSON IEP Policy File contains a single IEP Policy, then the file MUST only contain the single IEP Policy JSON object, e.g.

{
"id": "5945e5d4-b66d-40ad-9aec-cfadbcac961c",
    "name": "My IEP Policy #1",
    "description": "This is my first IEP Policy.",
    "iep_version": 2.0,
    "start_date": "2017-01-01T00:00:00Z",
    "end_date": null,
    "encrypt_in_transit": "must",
    "permitted_actions": "internally-visible-direct-actions",
    "affected_party_notifications": "must-not",
    "tlp": "red",
    "attribution": "must-not",
    "unmodified_resale": "must-not",
    "external_references": [ 
        "https://www.first.org/tlp", 
        "https://www.first.org/iep"
    ]
}

If the JSON IEP Policy File contains multiple IEP Policies, then the IEP Policy File MUST only contain a single JSON array containing all the IEP Policy JSON objects as members of the JSON array, e.g.

[
    {
        "id": "5945e5d4-b66d-40ad-9aec-cfadbcac961c",
        "name": "My IEP Policy #1",
        "description": "This is my first IEP Policy.",
        "iep_version": 2.0,
        "start_date": "2017-01-01T00:00:00Z",
        "end_date": null,
        "encrypt_in_transit": "must",
        "permitted_actions": "internally-visible-direct-actions",
        "affected_party_notifications": "must-not",
        "tlp": "red",
        "attribution": "must-not",
        "unmodified_resale": "must-not",
        "external_references": [ 
            "https://www.first.org/tlp", 
            "https://www.first.org/iep"
        ]
    },
    {
        "id": "b23e5adf-c4cc-4404-8c9c-e164e9c3158e",
        "name": "My IEP Policy #2",
        "description": "This is my second IEP Policy.",
        "iep_version": 2.0,
        "start_date": "2017-01-01T00:00:00Z",
        "end_date": null,
        "encrypt_in_transit": "may",
        "permitted_actions": "externally-visible-direct-actions",
        "affected_party_notifications": "may",
        "tlp": "amber",
        "attribution": "must-not",
        "unmodified_resale": "must-not",
        "external_references": [ 
            "https://www.first.org/tlp", 
            "https://www.first.org/iep"
        ]
    }
]

7.2 IEP Policy File naming

JSON IEP Policy Files SHOULD end with a ".iepj" file extension where possible.

7.3 IEP Policy File network accessibility

Creators SHOULD ensure that IEP Policy Files are made available at the network accessible URLs.

Providers SHOULD ensure that when IEP Policy References are used to mark information that Recipients will be able to access the referenced IEP Policy Files. To clarify, IEP Policy Files MAY be publicly accessible on the Internet, or MAY be housed within a private or restricted network – the only requirement is that the Recipient of the information marked with the IEP has the ability to access them.

7.4 Moving IEP Policy Files to a different URL

If an IEP Policy File needs to be moved to a different URL, then a URL redirection SHOULD be made to ensure that implementations that ingest old information marked with an IEP will still work as they will be redirected to the new IEP Policy File location.

If a URL redirection is not possible then Providers SHOULD reissue new versions of the old information marked with an IEP Policy Reference that points to the new IEP Policy File location. It is up to Providers to determine which old information is worth reissuing with an updated IEP Policy.

7.5 Caching IEP Policy Files

Recipients SHOULD keep a cached copy of all IEP Policy Files that contain IEP Policy Objects that mark information stored within its information repository, so that all information marked with IEPs will have a corresponding IEP locally available.

Recipients SHOULD periodically access remote IEP Policy Files that contain IEP Policy Objects that mark information stored within its information repository and update any IEP Policy Files in the IEP Policy File cache that were changed. It is up to Implementations' to determine how often this cache update takes place.

8. IEP Policy Reference

IEP Policy References are used to reference an IEP located in a different place. This functionality was designed to allow the development of community-shared IEPs to enable faster, automated sharing, and to reduce the communication overhead of embedding the same IEPs over and over again.

8.1 IEP Policy Reference Structure

A JSON IEP Policy Reference MUST be defined as a single JSON Object.

Each JSON IEP Policy Reference JSON Object MUST contain one of each of the IEP Policy Reference Statements as defined in the list below. The mandatory policy reference statements in IEP Framework 2.0 are:

8.2 IEP Policy Reference URL naming

As mentioned in section [INSERT CORRECT SECTION NUMBER], JSON IEP Policy Files SHOULD end with a ".iepj" file extension where possible. This in turn means that JSON Policy Reference URL SHOULD also end with a ".iepj" file extension where possible.

8.3 IEP Policy Reference or Embedded IEP Policy

It is up to the protocol or standard using IEP to decide if will apply the IEP to information contained within the information sharing protocol by embedding the IEP JSON Objects directly within the protocol or standard, or if it will make use of the IEP Policy Reference feature, or if it will support both.

Any protocols or standards that leverage IEP SHOULD support both embedded IEPs and IEP Policy References. This provides Providers with the greatest flexibility in how they apply the IEP Policy to the information they are sharing.

Embedded vs Referenced
Figure 2: Embedded vs Referenced

8.4 IEP Policy Reference lookups

IEP Policy Reference lookups SHOULD use the following steps to resolve the references to retrieve the IEP identified by the IEP Policy Reference:

  1. The id_ref Policy Reference Statement is read and the id_ref extracted.
  2. The Implementation checks if it has a cached version of the IEP whose id matches the id_ref.
  3. If the Implementation has a cached copy of the IEP, then the cached copy of the IEP is used.
  4. If the Implementation does not have a cached copy of the IEP, then the url Policy Reference Statement is read and the URL extracted.
  5. The Implementation checks if it has a cached version of the IEP Policy File whose URL matches the url Policy Reference Statement.
  6. If the Implementation has a cached version of the IEP Policy File whose URL matches the url Policy Reference Statement, and the cache timer has not expired, then the IEP Policy File is checked for an IEP whose id matches the id_ref extracted earlier.
  7. If the Implementation does not have a cached copy of the IEP Policy File, then the Implementation accesses the URL and downloads the IEP Policy File at the URL.
  8. The Implementation checks the IEP Policy File to ensure that it is valid.
  9. If the IEP Policy File is invalid then the process in section 11 – "Handling IEP Policy Errors" is followed.
  10. If the IEP Policy File is valid, then a copy of the IEP Policy File is stored in the IEP Policy File cache, and the IEP Policy File is the checked for an IEP whose id matches the id_ref extracted earlier.
  11. If the IEP has the correct id and is valid, then a local cached copy of the IEP is stored and used, and the Implementation lookup has ended.
  12. If the IEP Policy File is valid but there is no IEP with the correct id within the Policy File then the process in section 11 – "Handling IEP Policy Errors" is followed.  

    9. IEP Policy Reference Statements

Each IEP Policy Reference Statement is a JSON name / value pair (also known as a member), where the name is a string, and it is separated from the value by a colon. An example IEP Policy Reference Statement for the url Policy Reference Statement is shown below:

9.1 id_ref

The id_ref statement is used to identify the IEP that resides within the IEP Policy File referenced and located at the URL also provided. The id_ref statement MUST be a JSON name/value pair. The id_ref statement MUST be included in an IEP Policy Reference object. The id_ref statement name MUST be the JSON string "id_ref", and it must be in lowercase. The id_ref statement value MUST be a UUIDv4 or UUIDv5 identifier as defined in RFC4122 (A Universally Unique IDentifier (UUID) URN Namespace)3, and MUST be an identifier that exists (or had existed in the past) within the IEP Policy File referenced and located at the URL also included within the IEP Policy Reference object.

9.2 url

The url statement is used to specify the URL that will enable the recipient to access and read the IEP Policy File that contains the IEP that the information has been marked with.

The url statement MUST be a JSON name/value pair. The url statement MUST be included in an IEP Policy Reference object. The url statement name MUST be the JSON string "url", and it must be in lowercase. The url statement value MUST be a URL as defined in RFC3986 (Uniform Resource Identifier (URI): Generic Syntax)6, and MUST point to an Internet accessible IEP Policy File.

9.3 iep_version

The iep_version statement describes the IEP Framework version that this Policy Reference is.

The iep_version statement MUST be a JSON name/value pair. The iep_version statement MUST be included in an IEP Policy Reference object. The iep_version statement name MUST be the JSON string "iep_version", and it must be in lowercase. The iep_version statement value MUST be the JSON number "2.0" (without the quotes).  

10. IEP Policy Reference Complete Example

An example IEP Policy Reference JSON object is shown below:

{
    "id_ref": "01bc4353-4829-4d55-8d52-0ab7e0790df9",
    "url": "https://www.first.org/iep/2.0/first-tlp-iep.iepj",
"iep_version": 2.0
}

11. Handling IEP Policy Errors

This section provides guidance on how to handle IEP errors gracefully.

11.1 No IEP

If some information is received, and that information is not marked with an IEP, then the recipient MUST follow whatever guidelines they have agreed with the Provider. In this case no IEP has been applied to the information, and IEP is not being used to control how the recipient is allowed to use the received information.

11.2 Invalid IEP

If some information is received, and that information is marked with an IEP, but that IEP is invalid, then the recipient MUST contact the Provider to clarify what restrictions they should apply to the received information. The Creator or Provider SHOULD correct the Invalid IEP and the Provider SHOULD reissue an updated version of the information with a valid IEP.

11.3 Missing IEP

If some information is received, and that information is marked with an embedded IEP, but that embedded IEP is missing or otherwise unavailable, then the recipient MUST contact the Provider to clarify what restrictions they should apply to the received information. The Provider SHOULD reissue the information with a valid embedded IEP.

11.4 IEP Policy References pointing to non-existent IEP Policy Files

If some information is received, and that information is marked with an IEP Policy Reference, but that IEP Policy Reference points to a URL that is currently unreachable, then the following rules apply:

  1. If the Recipient had previously successfully accessed the IEP Policy File at the URL defined in the IEP Policy Reference, and the Policy File was valid, and one of the IEPs contained within the IEP Policy File had the same id as the id_ref contained within the IEP Policy Reference, and the Recipient has a cached copy of the IEP, then the Recipient MAY continue to use the previous cached copy of the IEP as if the IEP Policy Lookup worked correctly.

  2. If the Recipient had never successfully accessed the IEP Policy File at the URL defined in the IEP Policy Reference, then the Recipient MUST contact the Provider to clarify what restrictions they should apply to the received information.

  3. If the Recipient had previously successfully accessed the IEP Policy File at the URL defined in the IEP Policy Reference, and the IEP Policy File was valid, and the Recipient has a cached copy of the IEP, but the id_ref contained within the IEP Policy Reference does not match any of the id’s within the IEP Policy File, then the Recipient MUST contact the Provider to clarify what restrictions they should apply to the received information.

  4. A Recipient SHOULD keep a cached copy of all IEPs that mark information stored within its information repository, so that all information marked with IEPs will have a corresponding IEP locally available.

  5. If a recipient has attempted to contact the Provider for clarification on use of the information but has been unable to get a response, or if the recipient is unable (or unwilling) to contact the Provider, then the Default Unknown IEP applies (see section 11.6 - "Default Unknown IEP" later in this document).

The Creator SHOULD ensure that the missing IEP Policy File is made available at the URL. If an IEP Policy File needs to move to a different URL, then a URL redirection SHOULD be made to ensure that old information marked with an IEP will be redirected to the new location.

11.5 IEP Policy References pointing to non-existent id

If some information is received, and that information is marked with an IEP Policy Reference, and that IEP Policy Reference points to a valid IEP Policy File, but the id_ref contained within the IEP Policy Reference does not match any of the id’s within the IEP Policy File, then the following rules apply:

  1. If the Recipient had previously successfully accessed the IEP Policy File at the URL defined in the IEP Policy Reference, and the Policy File was valid, and one of the IEPs contained within the IEP Policy File had the same id as the id_ref contained within the IEP Policy Reference, and the Recipient has a cached copy of the IEP, then the Recipient MAY continue to use the previous cached copy of the IEP as if the IEP Policy Lookup worked correctly.

  2. If the Recipient had previously successfully accessed the IEP Policy File at the URL defined in the IEP Policy Reference, and the Policy File was valid, and the Recipient has a cached copy of the IEP, but the id_ref contained within the IEP Policy Reference does not match any of the id’s within the IEP Policy File, then the Recipient MUST contact the Provider to clarify what restrictions they should apply to the received information.

Implementations SHOULD periodically try to access IEP Policy Files that IEP Policy References with missing ids were referring to in order to check if an IEP with the correct id now exists within the IEP Policy File at the URL.

11.6 Default Unknown IEP

This IEP is designed to be the most restrictive as possible, as it is only used when Implementations know that an IEP was applied, but are unable to find out what it was, no longer have a cached copy of the IEP, and are unable to contact the Provider of the information to provide guidance as to which IEP should be applied.

In this case the IEP Framework applies a default restrictive policy to the information to ensure that it cannot be shared to any other entity other than the Recipient.   The Default Unknown IEP is below:

{
    "id": "e4eb1db1-e0fb-4200-9f4c-4c713bb197aa",
    "name": "FIRST IEP-SIG Unknown IEP",
"description": "This is the FIRST IEP-SIG Unknown Information Exchange Policy, and is applied whenever an implementation cannot access a previously assigned IEP.",
    "iep_version": 2.0,
    "start_date": "2017-01-01T00:00:00Z",
    "end_date": null,
    "encrypt_in_transit": "must",
    "permitted_actions": "internally-visible-actions",
    "affected_party_notifications": "must-not",
    "tlp": "red",
    "attribution": "must-not",
    "unmodified_resale": "must-not",
    "external_references": [ 
              "https://www.first.org/iep"
      ]
}

The FIRST IEP-SIG have also created a network accessible copy of the Unknown IEP Policy. The details are below:
Policy Name FIRST IEP-SIG Unknown IEP
Policy ID e4eb1db1-e0fb-4200-9f4c-4c713bb197aa
Policy URL first.org/iep/2.0/first-unknown-iep.iepj

12. Pre-defined FIRST IEP JSON Policy Files

The FIRST IEP-SIG have developed some standard IEP Policy Files and have made them Internet accessible to help Implementers standardize on a common set of IEPs. This will aid adoption and ensure all parties within an information sharing community know what behaviour is expected of them.

The FIRST IEP-SIG TLP Policies are all included in a single .iepj file and use the IEPJ JSON array structure described in section 7.1.

These policies are based on the FIRST TLP-SIG "TLP FIRST Standards Definitions and Usage Guidance — Version 1.0" available at first.org/tlp.

FIRST IEP-SIG IEP 2.0 TLP Red Policy File
Policy Name FIRST IEP-SIG IEP TLP Red
Policy ID 5e607e88-ab70-4977-8c1b-ee3a16b0f68c
Policy URL first.org/iep/2.0/first-tlp-iep.iepj
FIRST IEP-SIG IEP 2.0 TLP Amber Policy File
Policy Name FIRST IEP-SIG IEP TLP Amber
Policy ID 01bc4353-4829-4d55-8d52-0ab7e0790df9
Policy URL first.org/iep/2.0/first-tlp-iep.iepj
FIRST IEP-SIG IEP 2.0 TLP Green Policy File
Policy Name FIRST IEP-SIG IEP TLP Green
Policy ID 3903ce63-674c-4b70-9457-8c5527dd9115
Policy URL first.org/iep/2.0/first-tlp-iep.iepj
FIRST IEP-SIG IEP 2.0 TLP White Policy File
Policy Name FIRST IEP-SIG IEP TLP White
Policy ID 0d783790-b221-40c1-840a-5787330612c1
Policy URL first.org/iep/2.0/first-tlp-iep.iepj

13. Bibliography

  1. “RFC7159: The JavaScript Object Notation (JSON) Data Interchange Format,” March 2014. [Online]. Available: https://tools.ietf.org/html/rfc7159. ^
  2. “RFC4122: A Universally Unique IDentifier (UUID) URN Namespace,” July 2005. [Online]. Available: https://www.ietf.org/rfc/rfc4122.txt. ^
  3. “RFC3339: Date and Time on the Internet: Timestamps,” July 2002. [Online]. Available: https://tools.ietf.org/html/rfc3339. ^
  4. F. TLP-SIG, “ Traffic Light Protocol,” August 2016. [Online]. Available: https://www.first.org/tlp. ^
  5. “RFC3986: Uniform Resource Identifier (URI): Generic Syntax,” January 2005. [Online]. Available: https://tools.ietf.org/html/rfc3986. ^
  6. “RFC2119: Key words for use in RFCs to Indicate Requirement Levels,” March 1997. [Online]. Available: https://tools.ietf.org/html/rfc2119. ^

Abstract

The FIRST Information Exchange Policy (IEP) framework enables information providers to inform users of how they may use the information they receive. IEP ensures that both parties are aware of any restrictions on the use of the shared information and reduces the likelihood of misunderstandings.

Release Date

6 November 2019

Co-chairs

The FIRST IEP-SIG Co-chairs at the time of release were:

Editors

The FIRST IEP v2 JSON Implementation Standard was created and edited by the following people:

Contributors

The following people contributed to the FIRST IEP 2.0 JSON Implementation Standard:

Copyright © 2019 Forum of Incident Response and Security Teams, Inc. (FIRST). All Rights Reserved. The Information Exchange Policy 2.0 JSON Specification is licensed under the Creative Commons CC - BY-SA (Attribution+ShareAlike) license.