Getting Started with VERIS

This guide is aimed at organizations that are considering adopting the VERIS framework and is intended to help ease into the framework. It starts from a very basic adoption and gradually moves towards adopting more and more of the framework. Organizations that are considering adopting VERIS should read this guide

But, why? VERIS is a tool to help and organization collect incident data in a consistent way to support decision making. An organization's use of VERIS should be consistent with the type and level of decision making they wish to support. If you're considering adopting VERIS you should ask yourself "What do I want to know?" and prioritize the elements of VERIS that support that decision.

VERIS can be a little bit intimidating to look at. The important thing to remember is that the framework can be as simple or as complicated as you need for it to be. There are very few required fields in a VERIS record and many of them are only required if a particular attribute is present. For example, hacking variety is only required if hacking was present in the incident. Furthermore, nearly all of the required fields allow for unknowns. As an example, here is the simplest VERIS record that can exist:


That's not bad. You don't have to use every feature and you don't have to put your incidents into the JSON format that we have documented. The JSON format makes it easier to share incidents with other companies and validate your records, but you can work your way up to that.

To help you work your way up to that, we've put together some guidelines to help you ease your way into using VERIS internally.

Start with what you have

You're probably recording security incidents in your organization some way right now. Maybe it is in your help-desk ticketing system or maybe you have a unique system just for security. Maybe you store free-text Word documents with a narrative of what happened.

When you have an incient you probably record the date that it happened. Take the day, week, and month and just give them VERIS labels.


And you probably have an executive summary of what happened in the incident too.

summarySomething bad happened.

You might have some notes about how you discovered the incident. Or notes about any hacking, malware, social engineering that was observed. Even if this is free-text information, you can record it using VERIS fields.

discovery.notesReported by Frank in accounting.
hacking.notesaccessed server using stolen credentials.
social.notesFrank received a phishing message and he responded with his password.

For all of these you just need to figure out how you're going to gather the information from your existing tracking system and make it easy to find. If you're using free-text Word documents then you might decide to put a table at the top or bottom of the document and fill this in. If your data is in a database you might create another table for security incidents and have a small program that pulls from the database, modifies the data as needed and writes it into your VERIS table.

One idea that is often helpful is for an organization to go through their ticketing system and create a mapping of their fields to corresponding VERIS fields. This allows them to make at least some immediate use of data they already have because it can be translated into VERIS.

Add top-level enumerations

Once you've started to extract information from your incidents it's time to start adding in the enumerations that make data analysis easy. There are two required top-level enumerations in VERIS: whether or not this was an actual security incident and how it was discovered.

Nearly every help desk ticketing system will allow you to add new fields to your input form, so it could be as simple as creating a dropdown called discovery_method and populating it with the discovery_method enumerations. You can do the same with the security_incident field. And of course if you're using a Word document or an Excel spreadsheet just add another column for that variable.

It gets a bit trickier when you are already using a set of enumerations for these variables in your organization. You will have to create a mapping between what you use and the appropriate VERIS enumeration. You could decide to adopt the VERIS enumerations and revise previous incidents or you could try to use both sets of enumerations side-by-side. Another helpful option is to continue using your enumerations for these variables but convert them to the VERIS variable when sharing or analyzing the incident.

Add second-level enumerations

Now we're going to start to add more detail to the incident by going into the second-level enumerations. There are four top level enumerations that we didn't discuss in the last section: actor, action, asset, and attribute. It doesn't really make sense to have an enumeration for these because VERIS assumes that every incident has one of each of those. So instead we're going to go down a level and use a simple True/False for the second-level enumerations. For each of the following questions just answer Yes/No.


actor.externalWas there an external threat actor?
actor.internalWas there an internal threat actor?
actor.partnerWas there a partner threat actor?
actor.unknownWas there a threat actor but you don't know what kind?


action.hackingWas there evidence of hacking?
action.malwareWas there evidence of malware?
action.socialWas there evidence of social engineering?
action.misuseWas there evidence of misuse of privileges?
action.errorWas there an error that lead to the incident?
action.physicalWas there evidence of physical attack?
action.environmentalWas there an act of God that lead to the incident?
action.unknownAre we unsure what happened?


attribute.confidentialityIs it possible that confidential information was exposed?
attribute.integrityWas the integrity of any system affected?
attribute.availabilityWas there an availability loss?
attribute.unknownAre we unsure what was affected?


The list of assets that might be affected can be rather long so you might want to use a multi-select or give the person entering the data several drop down menus to choose from.

Another option would be to take the categories of asset and just ask Yes/No questions about them the way we did with the other variables.

asset.assets.serverWas a server affected by the incident?
asset.assets.networkWas a network device affected?
asset.assets.userWere any end-user devices affected?
asset.assets.terminalWere any terminal devices affected (e.g. ATM, Kiosk, etc)?
asset.assets.mediaDid the incident affect any paper documents, or storage media?
asset.assets.peopleWere any people compromised (e.g. Social Engineering)?
asset.assets.unknownAre we unsure what was affected?

Let's now imagine a fairly complex espionage incident. Last month an external actor used a phishing message to one of your users convincing him to run an attachment. The attachment installed malware which recorded the user's password. The attacker used those credentials to log into a server and create a backdoor. The backdoor was used to exfiltrate sensitive documents. Later a reporter contacted you and told you that your documents were showing up on an underground forum.

Using just what we've done so far, what kind of information can we record about the incident?

discovery_methodExt - found documents
discovery_notesFound out from a reporter at the newspaper
summaryExternal actor phishing results in malware on server
action.socialTrue was Frank in accounting again.

That is a really good VERIS record. Anyone on the VERIS Community Database project would be happy to get a record with that level of detail in it. And really, you haven't done anything hard yet. But you can start to develop trends around how many of your incidents involve physical actions (theft) versus error actions (loss) and how often a phishing email leads to compromised data. You can stop here and probably have better analytics than most organizations. VERIS doesn't have to be complicated.

Customize and privatize

VERIS was designed with sharing in mind, but not everything you want to record is fit for sharing. You might also have some extra things that you want to record but for which a VERIS variable does not exist. Not to worry, VERIS has you covered with the plus section.

Plus is the anything goes section of a VERIS record. So, for example, you might want to track which of your employees was the lead investigator on an incident. No problem, just make a record called plus.investigator or plus.lead or whatever you want to call it. You can have a variable for whether or not the incident is resolved. You could put information in there that does have an associated VERIS varible but which you would like to keep private anyway.

When you share the incident (should you ever decide to) you can leave out any variable that starts with "plus." If you're sharing a JSON representation of an incident, you can leave out plus all together or just send an empty plus section ("plus":{}).

This is your implementation intended to answer your questions. Do not feel like you have to VERISize every one-off malware infection or policy violation because you've adopted VERIS. Just because VERIS can model these incidents doesn't mean that it is a good use of your time. However, if you want to know how most malware takes root in your organization then it might make sense to VERISize every infection. It's up to you.

Add more detail

At this point your VERIS records are looking really good. You've got the basic details of what happened, and you're probably already starting to extract useful trends from the data. Now it's time to turn the volume up to 11 and start getting more detailed information.

If you have hacking in an incident it follows that you might want to know what kind of hacking. After all, hacking is a really big word that means a lot of things to different people. All seven of the threat actions have a subvariable named "variety" and most also have a variable named "vector". These will help you describe the kind of hacking that you're dealing with in a format that still lends itself well to analysis.

If you have an incident caused by an internal threat actor, you might want want to know what motivated the employee to act. Maybe you want to track what kind of employee it was or whether there had been any recent job change action. All of the actor variable have subvariables for variety and motive.

You might also want to record how long it took you to discover the incident and how much the incident impacted your organization. VERIS has variables for that too.

Let's VERISize another fictitious scenario with all the new variables we've added. In this case, you're notified by the local police department that an employeee in billing was arrested during a raid on an identity theft ring and is suspected of stealing identities from your company. You paid a forensic company $14,121 for an investigation which revealed that the employee had been accessing customer records without cause for three months. You also paid $8,000 to a law firm to make appropriate notification to the Attorney General in your state. Here is what the incident might look like in VERIS.

discovery_methodExt - law enforcement
discovery_notesFound out from local police
summaryEmployee misuse for identity theft purposes
action.misuse.varietyPrivilege abuse
action.misuse.vectorLAN access
impact.loss.1.varietyResponse and recovery
impact.loss.2.varietyLegal and regulatory

You can keep adding variables for all the parts of VERIS that you want to make use of and you can get really complicated models of a security incident. But all through this HOWTO we have been creating valid VERIS records which are only as complicated as the organization is willing to record.

Anonymize yourself and share

When you're using VERIS internally you might not care about victim demographics since your organization is going to be the only victim. But if you want to share this data with other organizations then it is helpful to know about the victim organization. VERIS makes it easy to share the relevant information without revealing the organization's name.

For example, VERIS records the country, industry, and industry of the victim organization. VERIS also has variables for the organization's employee count, revenue, and state (if in the U.S.). This is information that is useful for correlating impact with company size or for identifying which attack patterns affect industries but don't identify the company.

VERIS has a victim_id field which is used in the VERIS Community Database to name the victim organization. This is not a required field in VERIS and organizations sharing data with VERIS may choose to omit this field.