vz-risk / veris

Vocabulary for Event Recording and Incident Sharing (VERIS)

NOTE TO VERIS USERS

We have updated VERIS to version 1.3.2. This is primarily an update to add//modify a few enumerations, however it involves a significant change in the associated import scripts. From here we plan to update to version 1.4 which will fix schema hierarchy issues that may affect tooling. The primary example is making discovery_method and asset hierarchical like actor, action, and attribute. Version 2.0 will be for major feature additions. The primary one being considered is adding sequencing of the 4A's, timeline, and discovery method so that the sequence things happened in in the incident can be captured.

If you are using veris, please contact us at dbir [at] verizon.com to let us know how you use it and with what tools. If you have suggestions on changes we can/should make, please contact us or add an issue to the repository. We want to make sure the changes we make have minimal impact on all users and allow for easy upgrade at the user's convenience. To that end, we have saved a v1.3 release for those who chose not to upgrade as well as a v1.3 branch.

Running validation tests

Unit tests are written in nose, so you'll need to pip install nose. Then from the root of the repository, run nosetests. Python will automatically run the tests in the tests folder. If you want detailed output you can run nosetests --nocapture.

Writing unit tests

Each unit test is a VERIS json object wrapped inside another object. Each test object has three keys, "incident" should be a VERIS json object; "should" indicates whether the incident should pass or fail validation; "message is a string that explains why the incident should or should not pass validation." #--- http://veriscommunity.net

JSON Notes

Learn more about the JSON schema definition at http://json-schema.org/. We also are not enforcing the enumerations at the schema level, but instead have a separate file with the enumerations. Those may update a bit more often then the schema itself.

XML notes

The XML version has been archived until we can sync the XML with the JSON schema. The JSON schema represents the latest version of VERIS.

Index

• verisc.json - the JSON schema definition, compliant with the propoosed JSON standard. Merged with versc-labels.json to produce verisc-enum.json, verisc-merged.json, and keynames-real.txt
• verisc-labels.json - A list of enumerations with descriptions. Merged with versc.json to produce verisc-enum.json, verisc-merged.json, and keynames-real.txt
• verisc-enum.json - definition of the allowable enumerations within VERIS
• verisc-merged.json - The complete schema used for converting reviewed CSVs to json.
• bin/all.json - a json file of country codes used for converting CSVs to json.
• bin/build_standard_excel.py - script to read a merged schema file and produce the VERIS_Standard_Excel.xlsx file
• checkValidity.py - script (usable as module) to validate a json record against a schema file as well as aditional rules.
• convert-1.3.py - convert veris 1.2 json records to 1.3
• convert_1.3.X_to_1.3.Y.py - convert veris 1.3.X json records to 1.3.Y
• import_stdexcel.py - script (usable as module) to convert VERIS_Standard_Excel.xlsx Reviewed data to a csv to json.
• import_veris.py - script (usable as module) to import a csv to json. Chooses the correct import module, uses the rules module, and uses the checkValidity module.
• mergeSchema.py - Merges the schema file (e.g. verisc.json) and labels file (e.g. verisc-labels.json) to form the merged schema file (schema-merged.json)
• rules.py - script (usable as a module) to make json files valid (by adding 'unknown's) and to add rules (e.g. add asset.assets.web app if hacking.vector.web app is present)
• update_labels.py - script to update an existing labels file with a diff file.
• update_schema.py - script to update an existing schema file with a diff file.
• VERIS_Standard_Excel.xlsx - standard excel file used to produce importable data.
• vacf-rev20XX-vY_Y_Y.csv - VERIS <-> Mitre ATT&CK mapping structured as graph edges
• cis_csc_veris_map-rev20XX-vY_Y.xlsx - VERIS <-> CIS CSC mapping for both VERIS patterns and actions.
• joined_veris_json.md - Explain the joined VERIS format.

Required packages

The following packages are required to run the associated tools

Python

ipdb simplejson

Joined JSON

As the amount of VERIS json grows, it becomes unwieldly. As such, the VERIS toolchain is being updated to allow a joined form of VERIS. Please read more in the joined_veris_json.md file.

JSON-LD

JSON-LD is a format for storing linked data. the verisc.jsonld file is the graph representation of the veris schema rather than the json-schema format (the main format) for veris.

VERIS Common Attack Framework

The VERIS Common Attack Framework, (or VCAF) serves as a bridge to ATT&CK, covering the portions of VERIS not in ATT&CK with the aim of creating a holistic framework. At its very core, VCAF is made of two components: one is the conceptual mapping between VERIS and ATT&CK, and another is the extension of ATT&CK with techniques that cover all possible Threat Actions present in VERIS. This is helpful in using ATT&CK to make strategic decisions and understanding what tactical actions to take to address a strategic challenge. The mapping can be found as an edge list (or a join table for the more SQL minded) in bin/vcaf-rev2020-v1_0_3.csv in this repository.

Center for Internet Security (CIS) Critical Security Controls (CSCs) to VERIS Mapping

This mapping provides both pattern and control mappings for the Internet Security (CIS) Critical Security Controls (CSCs) to VERIS. This is helpful in using VERIS to make consistent control decisions. The mapping can be found in bin/cis_csc_veris_map-rev2020-v1_0.xlsx in this repository.

veris's Issues

add field actor.internal.job_change

This field would record if an internal actor has recently been hired, fired, promoted, or demoted. Passed over for a promotion might be good to have in that enumeration as well. @whbaker is going to dig up a previous enumeration that had similar variables for us to look at.

schema should not allow notes to be an empty string

Right now we have a fair number of incidents in the VERIS Community Database that have a notes field present but nothing in the notes field. Generally I don't like to include a field unless it has some information in it. So I would like to update the schema so that when a notes field is present the minimum length of the string is one. That way any empty notes fields will be caught and we can fix them.

Any objection to doing that?

plus type not defined

The plus object in the json schema does not have any type defined, which causes issues on schema validation. I believe type: ["object", "any"] is the appropriate way of defining this branch.

Add Source Code to the data variety enumeration

Right now when source code is stolen we code that up as Trade Secrets. After discussing the matter it seems like source code is worth calling out because it happens frequently enough that it might warrant it's own value in the enumeration, it may be distorting the view of other trade secret theft, and because source code is a type of data asset which has the ability to further an attack in a different way.

add field for secondary objective

In the 1.2.1 schema it is difficult to model an incident where an actor attacks a site and gain access only for the purpose of furthering an attack on a different target. A real-world example would be any of the strategic web compromises that FireEye has put on it's blog in 2013. http://www.fireeye.com/blog/technical/cyber-exploits/2013/05/ready-for-summer-the-sunshop-campaign.html

Right now we are proposing adding a field to the schema with a name like "secondary objective" which would hold an enumeration of sub-reasons why this site was hit.

At first we were thinking of just adding an actor motive of "furthering another attack" but we worry that doing that would blur the lines and make it harder to identify that this was an espionage attack, it just wasn't the primary target. We also considered having a boolean field that would just be a yes/no about whether this attack was being done to further a different attack.

convert1_3.py: separate write location from read location

Currently the convert1_3.py script will replace the source json file. It'd be nice to allow a different destination location so the original 1.2.1 files are not overwritten during conversion. This isn't a huge priority as it's a one shot deal and easily worked around.

vcdb directory needs to be trashed

VCDB now has it's own repo

Allow ranges in naics codes

This is a change more to the validation scripts, rather than a change to the schema since the schema already allows for strings in the victim.industry field.

We sometimes run into incidents where we know the victim was manufacturing but we don't know any more detail than that. So should the naics code be 31, 32, or 33? We will now allow putting in "31-33" if the victim is an unknown manufacturer, "44-45" for retail unspecified, and "48-49" for transportation unspecified.

Add pass-the-hash to hacking variety enumeration

Pass-the-hash or Pass the hash?

json2csv.py fails on OSX 10.8.2

I cloned the repository on my laptop running 10.8.2, installed simplejson using pip and tried to execute json2csv.py but received an error:

$ python json2csv.py
../vcdb/hhs_osint00001.json
    running with label:
    trying to parse impact
    running with label: impact
    trying to parse impact.overall_rating
        simply assigning: impact.overall_rating to Unknown
    trying to parse incident_id
        simply assigning: incident_id to hhs_osint00001
    trying to parse attribute
    running with label: attribute
    trying to parse attribute.confidentiality
    running with label: attribute.confidentiality
    trying to parse attribute.confidentiality.data
    trying to parse attribute.confidentiality.data
    running with label: attribute.confidentiality.data
    trying to parse attribute.confidentiality.data.amount
        simply assigning: attribute.confidentiality.data.amount to 506 (int)
    trying to parse attribute.confidentiality.data.variety
        simply assigning: attribute.confidentiality.data.variety to Medical
    trying to parse attribute.confidentiality.data_total
        simply assigning: attribute.confidentiality.data_total to 506 (int)
    trying to parse attribute.confidentiality.data_disclosure
        simply assigning: attribute.confidentiality.data_disclosure to Yes
    trying to parse discovery_method
        simply assigning: discovery_method to Unknown
    trying to parse schema_version
        simply assigning: schema_version to 1.2
    trying to parse action
    running with label: action
    trying to parse action.hacking
    running with label: action.hacking
    trying to parse action.hacking.vector
    trying to parse action.hacking.vector
        simply assigning: action.hacking.vector to Unknown
    trying to parse action.hacking.variety
    trying to parse action.hacking.variety
        simply assigning: action.hacking.variety to Unknown
    trying to parse security_incident
        simply assigning: security_incident to Confirmed
    trying to parse plus
    running with label: plus
    trying to parse plus.master_id
        simply assigning: plus.master_id to hhs_osint00001
    trying to parse actor
    running with label: actor
    trying to parse actor.external
    running with label: actor.external
    trying to parse actor.external.motive
    trying to parse actor.external.motive
        simply assigning: actor.external.motive to Unknown
    trying to parse actor.external.country
    trying to parse actor.external.country
        simply assigning: actor.external.country to Unknown
    trying to parse actor.external.variety
    trying to parse actor.external.variety
        simply assigning: actor.external.variety to Unknown
    trying to parse victim
    trying to parse victim
    running with label: victim
    trying to parse victim.victim_id
        simply assigning: victim.victim_id to Ashley Industrial Molding, Inc. Employee Welfare Benefit Plan
    trying to parse victim.industry
        simply assigning: victim.industry to 525120
    trying to parse victim.country
        simply assigning: victim.country to US
    trying to parse victim.employee_count
        simply assigning: victim.employee_count to 1 to 10
    trying to parse victim.state
        simply assigning: victim.state to In
    trying to parse timeline
    running with label: timeline
    trying to parse timeline.incident
    running with label: timeline.incident
    trying to parse timeline.incident.year
        simply assigning: timeline.incident.year to 2011 (int)
    trying to parse timeline.incident.day
        simply assigning: timeline.incident.day to 9 (int)
    trying to parse timeline.incident.month
        simply assigning: timeline.incident.month to 8 (int)
    trying to parse timeline.discovery
    running with label: timeline.discovery
    trying to parse timeline.discovery.unit
        simply assigning: timeline.discovery.unit to Unknown
    trying to parse source_id
        simply assigning: source_id to hhs
    trying to parse asset
    running with label: asset
    trying to parse asset.assets
    trying to parse asset.assets
    running with label: asset.assets
    trying to parse asset.assets.variety
        simply assigning: asset.assets.variety to S - Other
    output returned has 29 items
{'victim.industry': '525120', 'attribute': 'Confidentiality', 'attribute.confidentiality.data_disclosure': 'Yes', 'timeline.incident.month': 8, 'schema_version': '1.2', 'victim.victim_id': 'Ashley Industrial Molding, Inc. Employee Welfare Benefit Plan', 'victim.state': 'In', 'impact.overall_rating': 'Unknown', 'discovery_method': 'Unknown', 'timeline.incident.year': 2011, 'actor': 'External', 'actor.external.variety': 'Unknown', 'plus.master_id': 'hhs_osint00001', 'action.hacking.vector': 'Unknown', 'actor.external.country': 'Unknown', 'attribute.confidentiality.data_total': 506, 'timeline.discovery.unit': 'Unknown', 'actor.external.motive': 'Unknown', 'source_id': 'hhs', 'attribute.confidentiality.data.variety': 'Medical', 'asset.assets.variety': 'S - Other', 'action.hacking.variety': 'Unknown', 'victim.employee_count': '1 to 10', 'incident_id': 'hhs_osint00001', 'timeline.incident.day': 9, 'security_incident': 'Confirmed', 'action': 'Hacking', 'victim.country': 'US', 'attribute.confidentiality.data.amount': 506}
        0 combinations: 1
    -> not length of localnames, dumping as is
Traceback (most recent call last):
  File "json2csv.py", line 142, in <module>
    recursive(output, keylist)
  File "json2csv.py", line 85, in recursive
    writer.writerow(alldata)
  File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/csv.py", line 148, in writerow
    return self.writer.writerow(self._dict_to_list(rowdict))
  File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/csv.py", line 144, in _dict_to_list
    ", ".join(wrong_fields))
ValueError: dict contains fields not in fieldnames: victim.industry, attribute, attribute.confidentiality.data_disclosure, timeline.incident.month, schema_version, victim.victim_id, victim.state, impact.overall_rating, discovery_method, timeline.incident.year, actor, actor.external.variety, plus.master_id, action.hacking.vector, actor.external.country, attribute.confidentiality.data_total, timeline.discovery.unit, actor.external.motive, source_id, attribute.confidentiality.data.variety, asset.assets.variety, action.hacking.variety, victim.employee_count, incident_id, timeline.incident.day, security_incident, action, victim.country, attribute.confidentiality.data.amount

Add malware vector for software update

Need to decide on a proper name, but we want to have a way to model that malware was installed on a machine through the use of a software update server. In other words, an actor gained access to something like Microsoft System Center or Lumenion's product and used it to push malware to the endpoints. A real-world example is Operation Troy from March of 2013. https://blogs.mcafee.com/mcafee-labs/dissecting-operation-troy-cyberespionage-in-south-korea

Need a test to ensure that every key in verisc-labels is also present in verisc-enum

rename physical.variety.sabotage to something else

Because sabotage is a loaded word that implies insider even though that isn't always accurate.

Oh my God, it's a mirage! I'm telling y'all it's sabotage!

Bring back discovery_method of Ext - unrelated party

I have seen a couple incidents where this might still be the best choice for discovery method.

For example, there was an incident where an insider was taking photographs of credit cards for ID theft purposes. The incident was reported to the victim company by the manager at the photo development place to which she took the photos for printing.

Another incident involved documents that were published to the website that had sensitive information in them. A concerned member of the community reported the publishing error to the victim organization.

asset.assets is not supposed to be a required field.

Add defacement to integrity variety enumeration

We have so many website defacements and right now we model that by indicating an integrity loss variety of "modify data." We think that we can model a defacement more clearly by giving defacement it's own variable in the enumeration.

discovery_method rename "Int - reported by user" to "Int - employee"

The current wording can be a bit confusing because we don't like to think of IT people as users. This makes it clear that it was reported by an employee that saw something odd.

add field actor.name

We will add an array to the schema for strings that are used to identify the actor. Sometimes multiple actor names are given so we wanted to have an array rather than a string here. e.g. actor.name = ['Angry Dragon','DragonBall','Bob McCracken']

Simplify and rename action.physical subfields

RENAME physical.location to physical.vector and remove what is currently
physical.vector. Then we should add some enumerations to physical.variety
to reflect what is currently in vector.

When finished there will be one fewer subfields in the physical action

Put the creative commons license file in the repo

rename related_incidents to campaign_id

Campaign_id will hold a guid or some unique identifier to indicate that several incidents were part of the same campaign. @whbaker was going to find some definition of a campaign that he saw somewhere and share it with us.

Rename integrity.variety.misappropriation to Repurpose

We use Misappropriation to indicate that an attacker made use of an asset for something that it wasn't intended for. For example, installing malware on a machine to participate in a Distributed Denial of Service attack. However, to many people the word misappropriation means that money was stolen. To make the intended purpose more clear, we are going to rename Misappropriation to Repurpose to indicate than an asset has been repurposed by an attacker.

add additional metadata to the verisc.json schema file

Specifically, the schema should have a $shema property to indicate if it has been written to conform with Draft3 or Draft4.

Also, every array in the schema should have minItems set to 1 so that a validator will not allow empty arrays.

Finally, every array should have unique set to true so that an array may not contain more than one of the same value

Add digital certificates to data varieties

Digital certificates

Rename embezzlement to Possession abuse

The word embezzlement is another loaded term that people often think only has to do with money and so it doesn't always get marked when it should. It follows that we also get incidents where money was stolen and so embezzlement gets selected even though that might not be appropriate to describe the computer security incident.

To make things more clear, we want to rename attribute.integrity.Embezzlement to "Possession abuse"

Add new discovery_method enumerations

We decided in our meeting that we wanted to add some enumerations to reflect when an organization learns about a breach from a partner rather than an external party.

Prt - monitoring service
Prt - audit
Prt - antivirus
Prt - incident response
Prt - Unknown
Prt - Other
Ext - incident response
Ext - found documents
Ext - suspicious traffic
Ext - emergency response team
Int - data loss prevention

The key point in deciding whether the notification came from a partner versus an external party is whether or not there was some business arrangement with the group doing the notification. So if a customer of Verizon's Managed Security Service was notified by Verizon of malware activity that would be Prt - Monitoring service. However, if Verizon were investigating a case and discovered some other victim that had no business relationship with Verizon then the notification would be Ext - Unrelated.

asset.country should be a list, not a string

That way we can properly model when the affected assets are in multiple countries

Update checkValidity script for 1.3 schema

action.hacking.variety enumeration imports

From veriscommunity.net:

VERIS uses WASC's Threat Classification as a baseline for this list; descriptions of these attacks can be found there. We have considered incorporating or allowing other attack classifications (e.g., CAPEC), and would appreciate feedback from the community on this.

I agree that we should consider importing the CAPEC dictionary for use here. It allows for better alignment with the STIX/TAXII stack and is far more comprehensive, at the cost of a much larger set here (perhaps we could avoid some child nodes below a certain depth).

Alternately, it might be worth mapping our (and WASC's) enumerations to that standard.

Simplify asset characteristics

Right now, we have several "characteristics" that add context around assets: accessibility, ownership, management, hosting, and cloud. While these things can be determined when there's a forensics investigation, most users/use cases of VERIS don't use these fields. Given that, and since we'd like to simplify VERIS where possible, I propose an approach that simplifies and combines some of these into one field.

To me, the real research questions driving us to collect all those (or try) is that we (and others) are concerned that 3rd parties place our assets at risk in various ways. Furthermore, we care less about the simple fact of whether an asset was externally or internally hosted as much as we care whether that fact contributed to the incident.

How about one "asset.governance" field that includes appropriate enums from these separate field?

Suggested enum (array) for "asset.governance" combining accessibility, ownership, management, hosting:

Personally owned
Externally owned
Externally managed
Externally hosted
Internally isolated
Unknown
Not collected

Question: is "externally" the right descriptor here? Would "3rd party" be better?
I'm not sure we can fit the cloud options in here, but someone feel free to suggest that.

Add asset variety for configuration management

We already have a malware vector for software update where a compromised server that is trusted by a workstation sends malware. However, we might also need an asset variety to cover the compromised server. I would like to propose adding "S - Configuration management" to the asset enumeration to cover incidents like this one: http://classic.slashdot.org/story/14/05/17/051214

change data.state to an array rather than a string

So we can model that some of the data was stored encrypted and some of it was stored unencrypted.

Add Not collected to all enumerations

Should we add a value of Not collected to all of our enumerations so we can differentiate between stuff that we don't know and stuff that we didn't even try to collect.

add field discovery.notes

Right now there is no field to explain the discovery classification.

Need a test to ensure that every key in verisc-enum is also present in verisc-labels

import simplejson as sj

enum = sj.loads(open('verisc-enum.json').read())
lab  = sj.loads(open('verisc-labels.json').read())

def findValues(path, inDict):
  for eachKey in inDict.keys():
    if type(inDict[eachKey]) == type({}):
      findValues(path + [eachKey],inDict[eachKey])

    if type(inDict[eachKey]) == type([]):
      listLabels = findLabels(path+[eachKey],lab)
      for eachItem in inDict[eachKey]:
        if eachItem not in listLabels:
          print "%s is not in %s of labels" % (eachItem,path + [eachKey])


def findLabels(path,inDict):
  if len(path) > 1:
    return findLabels(path[1:],inDict[path[0]])
  else:
    return inDict[path[0]].keys()

if __name__ == "__main__":
  findValues([],enum)

checkValidity script should ensure internal consistency for attribute and plus fields

Right now we have some variables that we collect in the plus section such as plus.attribute.confidentiality.. We have found some instances where these variables were set even though the incident did not have a confidentiality attribute affected.

Script should check if incident.plus.attribute.confidentiality is present. Then check if incident.attribute.confidentiality is present. Raise error if not present

Rename physical.tampering to physical.skimming or just add it

We talked about having an enumeration for when someone uses a hand-held skimming device vs. when they actually tamper with a machine like in ATM skimming.

Remember, we added "Possession abuse" as a misuse variety, so I think that using "Posession abuse" and "Tampering"

asset.country not properly defined

The schema indicates that asset.country should be a list but does not indicate a list of what. That needs to be changed so that asset.country is a list of strings. Thanks to @davidski for pointing that out.

add victim.region and actor.region fields

Sometimes we know that a victim was in Asia but we do not know the specific country. We wanted to add a field that would allow us to capture what we do know. The proposal is to create a six digit string which combines the United Nations region codes (http://unstats.un.org/unsd/methods/m49/m49regin.htm). So, for example, If we knew that an incident happened in Africa, the code would be 002000. If we knew that it was North Africa then the code would be 002015.

One big advantage to doing it this way is that the UN has already created a list of countries and which region and subregion codes they belong to. If we were to create our own list we would have to do that work ourselves. Yuck.

We should add a field to track when partner data is compromised

I think we might have discussed and dismissed this, but we should reconsider. We have quite a few instances when company A is hacked and data from company B is compromised. Since 3rd party risk is an important issue and many are interested, this supports an important research question - How often do incidents compromise partner data stored on the victim's systems?

Add Server - Unknown to Asset Types

Right now we're using S - Other whenever we know that a server was compromised but we don't know what kind of sever. It would be better to use S - Unknown for this situation and use S - Other when we know what kind of server it was and it is something that we don't have a variable for in the enumeration.

hacking.vector.partner label change

The enumeration will still be hacking.vector.partner but we will change the label to indicate that we use this for when a partner's credentials are stolen and used to attack the victim.

discovery_method rename "Int - IT audit" to "Int - IT review"

The word audit implies that a formal inspection of controls and log files was being done. Often times something much less formal is done which results in discovery.

VERIS 1.2 conversion error for United States

convert-1.2.py uses country_to_code.json to convert country names to the correct two letter codes. The script converts pre-1.2 VERIS files containing "United States of America" to "United States" before doing the lookup, but the country-to-code.json file contains "United States of America" and not "United States". This causes all conversion for US entries to fail

Swapping those values around in convert-1.2.py allows the run to complete.

Consider adding "routine internal maintenance" to discovery methods

Example is a skimmer discovered by routine checkup of ATM. Applies to systems/apps as well.

Add data variety of Virtual Currency

We would make the label "Virtual currency, including crypto currencies." This is to help us model incidents where bitcoins are stolen or even in-game currency that can be used to purchase virtual stuff.

Add enum "victim" or "internal" to data_victim

Maybe we just leave it blank instead, but there is no obvious option to select when info belonging to the compromised org was stolen (eg, internal documents).

Assemble the full schema (including the enumerations) for validation

See https://gist.github.com/blackfist/9672061

Change victim.country to an array

So we can model when a victim has assets that are affected in multiple countries.

checkValidity specify plus section

Right now the checkValidity script does not do any checking of the plus section because that is the area where organizations are invited to put whatever they want. However, and organization may want to validate what they put into the plus section.

The checkValidity script should be updated so that you can specify a file that contains a json schema for the plus section which will be validated along with the rest of the incident.