Skip to content

Commit 40acd29

Browse files
chris-counteractivechris-counteractive
committedOct 30, 2020
Update README and structure.
1 parent c150c59 commit 40acd29

File tree

2 files changed

+83
-77
lines changed

2 files changed

+83
-77
lines changed
 

‎objects/built-in/user-account.yml ‎objects/user-account/user-account.yml

File renamed without changes.

‎readme.md

+83-77
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,23 @@
1-
# SCOPE - STIX Custom Objects, Proposals, and Extensions
1+
# SCOPE: STIX Custom Objects, Proposals, and Extensions
22

33
A repository and namespace for STIX custom objects and extensions, as well as proposals for how they could be used. Because we see opportunities to expand the _scope_ of STIX's influence in infosec, naturally.
44

5-
This is intended for discussion and evaluation, to try to find any devils in the details.
5+
Built for discussion and evaluation, to try to find any devils in the details. Please open an issue or submit a pull request if you're interested in contributing.
66

7-
**Caveat:** Please consider this alpha content, not (yet) intended for production use. However, all customizations should be [compliant with the STIX 2.1 spec](https://docs.oasis-open.org/cti/stix/v2.1/csprd01/stix-v2.1-csprd01.html#_Toc16070825), so it shouldn't break anything to try it out.
7+
**Caveat:** This is alpha content, not (yet) intended for production use. However, all customizations should be [compliant with the STIX 2.1 spec](https://docs.oasis-open.org/cti/stix/v2.1/csprd01/stix-v2.1-csprd01.html#_Toc16070825), so it shouldn't break anything to try it out.
88

99
## Goals
1010

1111
1. Support wider adoption of STIX data abstractions in detection and response.
1212

13-
A very modest expansion of observable types and relationships will go a long way here - this namespace includes two new observable types to describe systems and sessions.
13+
A small expansion of observable types will go a long way towards addressing the applicability of STIX to detection and response use-cases.
1414

15-
1. Support improved data source documentation and relationships in MITRE ATT&CK.
15+
1. Support improved [data source documentation](https://github.com/mitre-attack/attack-datasources) and relationships in MITRE ATT&CK.
1616

17-
Capturing object _types_ (vs. just instances) as first-class STIX domain objects lets us capture useful metadata (like data sources!) and empowers more flexible relationships. Using a single custom domain object type we show how this could work, along with some of its specific benefits.
17+
Describing object _types_ (vs. just instances) as first-class STIX domain objects lets us attach useful metadata (like data sources!) and empowers more flexible relationships.
1818

19-
## Constraints
19+
1. Stay within the STIX spec and keep customizations minimal to reduce standards proliferation.
2020

21-
1. Stay within the latest STIX spec to leverage its strengths, avoid standards proliferation, and maximize consistency with ATT&CK.
22-
1. Propose the minimum number of customizations necessary to meet the goals (i.e., the "minimum effective dose").
23-
1. Incorporate lessons from other prior art.
2421

2522
## Background
2623

@@ -36,13 +33,13 @@ We love STIX, but we've run into two limitations:
3633
3734
We appreciate the desire to manage the scope of the STIX project, but we respectfully disagree.
3835

39-
1. Security operations, digital forensics, and incident response frequently requires sharing information across organizational boundaries. We commonly share information between departments, sister organizations, regulators, attorneys, law enforcement, vendors, customers, and more. It just tends to be _ad hoc_, governed by whatever tools or procedures happen to be in place.
40-
1. STIX already has features for controlling how information should be shared (_e.g._, [TLP](https://www.cisa.gov/tlp)): it's not exclusively designed for sharing information "widely."
41-
1. Attacks are often launched from one organization's systems and cloud tenancies into other organizations, so the distinction between "friendly assets" and "attacker infrastructure" is already pretty blurry.
42-
1. It leads to arbitrary distinctions (_e.g._, having a `user-account` observable in scope, but the system a `user-account` uses out of scope).
36+
1. Security operations, digital forensics, and incident response frequently require sharing information across organizational boundaries. We commonly share between departments, sister organizations, regulators, attorneys, law enforcement, vendors, customers, and more. It just tends to be _ad hoc_, governed by whatever tools or procedures happen to be in place. Lots of word documents and pdfs.
37+
1. STIX has features for controlling how information should be shared (_e.g._, [TLP](https://www.cisa.gov/tlp)): it's not exclusively designed for sharing information "widely."
38+
1. Attacks are often launched from victims' compromised systems, so the distinction between "friendly assets" and "attacker infrastructure" is already pretty blurry.
39+
1. It leads to arbitrary distinctions (_e.g._, having a `user-account` observable in scope, but the system a `user-account` _uses_ out of scope).
4340
1. Parallel efforts for describing "friendly" or "internal" observables would have to solve problems STIX already solved ... along with compatibility with STIX itself!
4441

45-
**Bottom line:** we think the STIX model has a lot to offer beyond just CTI, particularly in the realm of detection and response, and a few custom objects would vastly increase its usefulness without unduly compromising concision.
42+
**Bottom line:** we think STIX has a lot to offer beyond just CTI, particularly in the realm of detection and response, and a few custom objects would vastly increase its usefulness without unduly compromising concision.
4643

4744
Fortunately STIX v2.1 supports [custom objects and extensions](https://docs.oasis-open.org/cti/stix/v2.1/cs01/stix-v2.1-cs01.html#_3wlhv7hxh2en), and this project respects those constraints, making it compatible with existing spec.
4845

@@ -52,48 +49,48 @@ We love STIX, but we've run into two limitations:
5249

5350
Also, having _types_ as first-class STIX objects makes relationships much more powerful. You could say things like "`tool` _t_ creates `process` objects with properties of a certain kind."
5451

55-
Fortunately, with custom objects we can make this happen too!
52+
With custom objects we can make this happen too!
5653

5754
## Custom Observable Types
5855

5956
### System
6057

6158
- System (`x-scope-system`)
62-
- Physical System Extension (`x-scope-physical-ext`), _e.g._, laptop, desktop, server in rack
59+
- Physical System Extension (`x-scope-physical-ext`), _e.g._, laptop, desktop, smartphone
6360
- Virtual System Extension (`x-scope-virtual-ext`), _e.g._, vm, container
6461
- Datastore System Extension (`x-scope-datastore-ext`), _e.g._, database, wiki, s3
65-
- Appliance System Extension (`x-scope-appliance-ext`), _e.g._, F5 load balancer, wifi gateway, web application firewall
66-
- Platform System Extension (`x-scope-platform-ext`), _e.g._, microsoft 365 tenancy, salesforce instance
62+
- Appliance System Extension (`x-scope-appliance-ext`), _e.g._, load balancer, wifi gateway, WAF
63+
- Platform System Extension (`x-scope-platform-ext`), _e.g._, cloud email tenant, CRM instance
6764

6865
The concept of a "system" (_a.k.a._, host, endpoint, asset) is ubiquitous, and has an intuitive definition, something like "a logically distinct combination of hardware and software." A system is where most observables are in fact observed: `file`, `process`, `user-account`, _etc._, are observed on systems.
6966

70-
Except unfortunately STIX doesn't have a type for them. CybOX used to (called "System"), ECS does (called "Host"), and it's floated as a possibility for STIX v2.2+ in the working documents, but it's not in the current spec.
67+
Except STIX doesn't have a type for them. CybOX used to (called "System"), ECS does (called "Host"), and it's floated as a possibility for STIX v2.2+ in the working documents, but it's not in the current spec.
7168

7269
Another way to think of a system is as anything supporting sessions (see below), but regardless of the formal definition, it's a prerequisite to making STIX more relevant to detection and response. We think it'll help the CTI use-case too.
7370

74-
We propose bringing it back as a new, inclusive `system` type with extensions to capture the fact that systems aren't just physical desktop boxes anymore.
71+
We propose bringing it back as a new, inclusive `system` type with extensions to capture the fact that systems aren't just physical desktop boxes anymore. See the details and comments in [system/x-scope-system.yml](./objects/system/x-scope-system.yml)
7572

7673
### Session
7774

7875
- Session (`x-scope-session`)
7976

8077
A session is any period of interaction between an account and a system (see above). ECS has an open RFC that captures their variety well: sessions can be local, remote, network, or more, and on any type of system (virtual, physical, appliance, _etc._).
8178

82-
They're characterized by an account, system, start time, and end time, though in the simplest case they may be the same (say, via a single REST call). Also, one or the other times may be unknown.
79+
They're characterized by an account, system, start time, and end time, though in the simplest case these times may be the same (say, for a single REST call). Also, one or the other times may be unknown.
8380

84-
Current related STIX fields like `user-account` first and last logon times don't give sufficient granularity to link accounts with observables in the context of detection and response, and they don't capture the reality that user accounts can access many systems.
81+
Current STIX fields like `user-account`'s first and last login times don't give sufficient granularity to describe activity in the context of detection and response, and they don't capture the reality that user accounts can access many systems.
8582

86-
Bringing a `session` type into the mix provides a great tool for sharing information about **timelines**, which are incredibly useful for detection, response, and CTI alike.
83+
Bringing a `session` type into the mix provides a great tool for sharing information about **timelines**, which are critical for detection, response, and CTI alike.
8784

8885
### API
8986

9087
- API (`x-scope-api`)
9188

92-
Application programming interfaces (APIs) are central to many adversary techniques, but there's currently no way to describe an API in STIX. Like with `system`, there was such a type in CybOX, but it was culled.
89+
Application programming interfaces (APIs) are central to many adversary techniques, but there's currently no way to describe them in STIX. Like with `system`, there was such a type in CybOX, but it was culled.
9390

94-
We recommend resurrecting it, if only for its applicability to ATT&CK.
91+
We recommend resurrecting it, if only for its applicability to ATT&CK. It might be a bit tricky to get the details right, but the juice will be worth the squeeze.
9592

96-
For example, when discussing or detecting ATT&CK `attack-pattern`s like [process injection](https://attack.mitre.org/techniques/T1055/) and its sub-techniques, it's helpful to refer to specific Windows APIs and API calls.
93+
For example, when discussing ATT&CK `attack-pattern`s like [process injection](https://attack.mitre.org/techniques/T1055/) and its sub-techniques, it's helpful to refer to specific Windows APIs and API calls.
9794

9895
Like `system`, `api` would benefit from an updated definition to include the breadth of modern API types, from OS system calls to RPC to REST.
9996

@@ -107,75 +104,73 @@ This gets a little meta, but bear with us 😃: the idea is to capture details a
107104

108105
Put another way: currently the details of the `process` type live in a word document and a non-normative json schema. They're not STIX data. This would allow us to capture that in a STIX object itself, _a la_:
109106

110-
```javascript
107+
```json
111108
{
112-
type: "x-scope-stix-type",
113-
id: "x-scope-stix-type--GUID-FOR-PROCESS-TYPE"
114-
name: "process",
115-
schema: /* json schema like https://github.com/oasis-open/cti-stix2-json-schemas/blob/master/schemas/observables/process.json */
116-
external_references: [/* refs */]
109+
"type": "x-scope-stix-type",
110+
"id": "x-scope-stix-type--GUID-FOR-PROCESS-TYPE",
111+
"name": "process",
112+
"schema": { /*json schema from https://github.com/oasis-open/cti-stix2-json-schemas/blob/master/schemas/observables/process.json */ },
113+
"external_references": [ /* refs */ ]
117114
/* other fields */
118115
}
119116
```
120117

121118
This provides some benefits:
122119

123-
1. You can store data that applies to all objects of that type. For the programmers out there, think static members in C++/Java or prototype properties in javascript.
124-
125-
The specific use-case that inspired this was trying to use SCO abstractions as the basis for improving MITRE ATT&CK's data sources. For example, it'd be useful to describe what Windows event logs would help us populate a `process` observable. With a `type` object, one way to do this is to add this data under the `external_references` field of the `type` object corresponding to the `process` SCO (or to a custom `evidence_locations` field, or whatever).
126-
127-
1. Relationships (SROs) can refer to types in general rather than just instances of a type.
128-
129-
It can be useful to describe the relationships of one SCO type to another:
130-
131-
- Some of these, like a `user-account` creating a `process`, are **embedded relationships** captured by a `_ref` field in the object - these are well-suited to `external_references` on the SCO type as noted above. In pseudo-code:
132-
```javascript
133-
{
134-
type: "x-scope-stix-type",
135-
id: "x-scope-stix-type--GUID-FOR-PROCESS-TYPE"
136-
name: "process",
137-
external_references: [
138-
{/*info about windows EID 4688 and how it supports filling the creator_user_ref field (the user-account -> process embedded relationship)*/}
139-
]
140-
}
141-
```
142-
- Others, like a `process` setting a `windows-registry-key`, don't have embedded `_ref`s so could be done with a new relationship object (SRO). With a first-class `type` SDO, we can create an SRO that captures this, and attach `external_references` or other fields to that SRO:
143-
```javascript
144-
{
145-
type: "relationship",
146-
id: "relationship--GUID",
147-
relationship_type: "set",
148-
source_ref: "x-scope-stix-type--GUID-FOR-PROCESS-TYPE",
149-
target_ref: "x-scope-stix-type--GUID-FOR-REGISTRY-KEY-TYPE",
150-
external_references: [
151-
{/*info about sysmon EID 13 and how it links process info to registry key activity (the process -> windows-registry-key relationship, currently not embedded)*/}
152-
]
153-
}
154-
```
120+
1. **You can store data that applies to all objects of that type.** For you programmers, think static members in C++/Java or prototype properties in javascript.
121+
122+
Improving MITRE ATT&CK's data sources led to the idea of storing them in SCO types themselves. It'd be useful to describe what Windows event logs would help us populate a `process` observable, for example. With a first-class `stix-type` object, we could add this data under the `external_references` field of the `stix-type` object for the `process` SCO (or to a custom `evidence_locations` field, or whatever).
123+
124+
1. **Relationships (SROs) could then refer to types rather than just instances.**
125+
126+
It can be useful to describe the relationships of one SCO type to another. Some of these, like a `user-account` creating a `process`, are **embedded relationships** captured by a `_ref` field in the object. These are well-suited to `external_references` on the SCO type as noted above. In pseudo-code:
127+
128+
```json
129+
{
130+
"type": "x-scope-stix-type",
131+
"id": "x-scope-stix-type--GUID-FOR-PROCESS-TYPE",
132+
"name": "process",
133+
"external_references": [
134+
{/*info about windows EID 4688 and how it supports filling the creator_user_ref field (the user-account -> process embedded relationship)*/}
135+
]
136+
}
137+
```
138+
139+
Others, like a `process` setting a `windows-registry-key`, don't have embedded `_ref`s. These could be described with a new relationship object (SRO). With a first-class `stix-type`, we can create an SRO that captures this, and attach `external_references` or other fields to that SRO:
140+
141+
```json
142+
{
143+
"type": "relationship",
144+
"id": "relationship--GUID",
145+
"relationship_type": "set",
146+
"source_ref": "x-scope-stix-type--GUID-FOR-PROCESS-TYPE",
147+
"target_ref": "x-scope-stix-type--GUID-FOR-REGISTRY-KEY-TYPE",
148+
"external_references": [
149+
{/*info about sysmon EID 13 and how it links process info to registry key activity (the process -> windows-registry-key non-embedded relationship)*/}
150+
]
151+
}
152+
```
155153

156-
Or as another example (unrelated to logs), let's say we wanted to express "the `attack-pattern` [Create or Modify System Process: Windows Service (T1543.003)](https://attack.mitre.org/techniques/T1543/003/) creates `process` observables, specifically with the extension `windows-service-ext`. The [current model](https://docs.oasis-open.org/cti/stix/v2.1/csprd01/stix-v2.1-csprd01.html#_Toc16070618) doesn't allow relationships between `attack-pattern`s and observable types, but with a new `type` object you could express it easily (and with other metadata, including references).
154+
Take another example unrelated to logs: let's say we wanted to express "the `attack-pattern` [Create or Modify System Process: Windows Service (T1543.003)](https://attack.mitre.org/techniques/T1543/003/) creates `process` observables. The [current model](https://docs.oasis-open.org/cti/stix/v2.1/csprd01/stix-v2.1-csprd01.html#_Toc16070618) doesn't allow relationships between `attack-pattern`s and observable types, but with a `stix-type` object you could express it easily.
157155

158156
1. You can transmit the STIX specification as STIX data. It's like having a compiler written in the language itself.
159157

160-
This also supports setting constraints on concrete objects of a certain type, but that's a discussion for another day.
161-
162158
## Usage
163159

164-
The proposed objects are stored in the [objects](./objects/) directory as yaml files. These can be transformed into a reasonable facsimile of the STIX spec format using the node script in the [render](./render/) folder.
165-
166-
```bash
167-
# with nodejs installed
160+
The proposed objects are stored in the [objects](./objects/) directory as yaml files. These can be transformed into a reasonable facsimile of the STIX spec format using the node script in the [render](./render/) folder.
168161

169-
cd render
162+
Forgive the spaghetti-code ejs template - this is just to prove you can build a similar looking spec from yaml, which would be easier to serialize into the `stix-type` objects described above. And would be easier to collaborate on via github ...
170163

171-
npm install
164+
```bash
165+
# needs nodejs
166+
$ cd ./render
167+
$ npm install
172168

173-
# right now template.ejs is the only template
174169
# user-account.yml is a built-in, included for testing:
175-
./render/render.js render/template.ejs objects/built-in/user-account.yml > temp/user-account.html
170+
./render/render.js render/template.ejs objects/user-account/user-account.yml > user-account.html
176171

177172
# custom types are stubs for now:
178-
./render/render.js render/template.ejs objects/system/x-scope-system.yml > temp/system.html
173+
./render/render.js render/template.ejs objects/system/x-scope-system.yml > system.html
179174
```
180175

181176
## Prior Art
@@ -184,3 +179,14 @@ npm install
184179
1. MITRE [Cyber Analytics Repository](https://car.mitre.org/) (CAR)
185180
1. [CyBOX](https://cyboxproject.github.io/releases/2.1/), an archived project that was worked into STIX SCOs.
186181
1. [Elastic Common Schema](https://www.elastic.co/guide/en/ecs/current/ecs-field-reference.html) (ECS), used primarily to add normalized fields to logging data.
182+
183+
## License
184+
185+
Copyright 2020 Counteractive Security
186+
187+
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License in the [LICENSE](./LICENSE) file or at:
188+
189+
http://www.apache.org/licenses/LICENSE-2.0
190+
191+
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
192+

0 commit comments

Comments
 (0)
Please sign in to comment.