ocsf / ocsf-docs Goto Github PK
View Code? Open in Web Editor NEWOCSF Documentation
License: Apache License 2.0
OCSF Documentation
License: Apache License 2.0
The documentation says:
Profiles overlay additional related attributes into event classes and objects allowing for cross-category event class augmentation and filtering. Event classes register for profiles which can be optionally applied, or mixed into event classes and objects, by a producer or mapper.
The system event is:
"attributes": {
"$include": [
"profiles/host.json",
"profiles/user.json",
"profiles/malware.json"
],
"device": {
"group": "primary",
"requirement": "required",
"profile": null
},
"actor_process": {
"requirement": "required",
"profile": null
}
}
The host profile is:
"attributes": {
"device": {
"requirement": "recommended"
},
"actor_process": {
"requirement": "optional"
}
}
The $include
directive seems to say that the host profile is always included in the system event, downgrading the device and actor_process attributes from required to not required. There are only two events that have properties modified by a profile: inventory and system, in both cases by the host profile. That raises the question of whether that is an error in the two events, or in the host profile. It seems strange that a system event would always require a device attribute except when operating under the host profile - wouldn't it make more sense to just make the device attribute always non-required regardless of profile?
Is there ever a circumstance in which the system event would not include the host (or user or malware) profile? If so, what controls whether $include directives are executed? The context is schema generation - it seems that a system event could include any attribute listed in the system event or any included profile. The expected behavior of producers and consumers seems ill-defined if the attributes permitted in an event is variable.
I am currently trying to understand how OCSF compares to STIX. I noticed in the present FAQ (https://github.com/ocsf/ocsf-docs/tree/main/FAQs) that you planned to add an explanation on how they are complementary.
As I cannot seem to find an answer to my question online, would it be possible to obtain one here?
Thanks.
"Understanding OCSF" discusses personas at a high level, but in order to be "agnostic to storage format, data collection and ETL processes", an additional level of communication detail is required. Being agnostic requires defining what information is collected, stored and transformed without regard to the data formats used to represent that information.
Current:
The author works directly with the schema as described. But producers, mappers and analysts work with data that corresponds to (can be validated by) the schema.
Proposed:
A communication diagram would show personas exchanging documents or messages, or in NIEM terminology, "Information Exchange Packages (IEPs) are the actual messages that carry data and are exchanged between stakeholders." The schema itself is not a persona or communication endpoint, it is used by them when validating data or writing analytics.
Originated from ocsf-schema
PR ocsf/ocsf-schema#807
I believe there is an important relationship between the observable
datatypes and how the observable objects are identified.
For instance, I believe the OCSF translator looks at the datatype, and when the datatype of a given object matches an observable type, it identifies that object as an observable.
Therefore, removal of an observable datatype from an object could be a breaking change.
We should find some way to work this into our documentation (and our process)
The topic that triggered this - Changing captions of an enum attribute is also a breaking change, since captions are used as values of the sibling string attributes.
We should create a FAQ to formalize what constitutes as a breaking change. We can use this issue to discuss and arrive at a consensus for what a breaking change for OCSF is.
I recommend adding a FAQs directory to this (ocsf-docs) directory. It could refer to other existing docs (eg the white papers, the contributing page, the governance page). One useful section would be on a series of questions on how OCSF relates to other activities (OCA, Mitre Att&ck, STIX, CACAO, TAC, OpenC2, Kestrel, PACE, NIEM, ...).
https://github.com/ocsf/ocsf-docs/blob/main/Understanding%20OCSF.md documents the timestamp_t
format as "milliseconds since the unix epoch", however the example payload provided by https://schema.ocsf.io/sample/1.2.0/classes/base_event produces a value for the time
field in the quadrillions (e.g. "time": 1718905365392963,
) which only makes sense if interpreted as microseconds, not milliseconds.
Is the error in the documentation, or the sample event implementation?
Either the document should be removed from the repository or a new version should be posted that is non-confidential.
Ideally this should be posted as a Markdown file so it can be collaborated on.
Add to Docs information on Groups.
In the following example a group is part of the Event Class.
group โ For each attribute ensure you add a group value. Valid values are - Classification, Context, Occurrence, Primary
example:
"hw_bios_manufacturer": {
"description": "The BIOS manufacturer.",
"group": "primary",
"requirement": "optional"
},
A topic of discussion that often comes up from OCSF adopters is "When should I use/create an Extension versus when should I use/create a Profile. The Understanding OCSF
document does a pretty good job of explaining the two, but I think adopters still run in to problems where they are not sure the correct approach to take under various scenarios. Perhaps we can add a few scenarios where we can outline when it is appropriate to choose a Profile and when it is appropriate to choose an Extension?
https://schema.ocsf.io/ is down, I am not able to view the OCSF schema.
Currently, the only way to view the guidelines of attribute grammar in OCSF is via a local instance of the ocsf_server. Instead, we should provide an easy access to it by creating a .md file accessible in the repo.
A simple .md file should suffice.
Once created, link this file in the contribution guideline file - line# 39
Not sure how or if this should be merged with our formal docs. However we discussed this question of how to determine if a log is supported the other day.
Here is my attempt to describe a process to determine if a log is supported. I would call this 'ocsf data onboarding'. I think it could use additional details on navigating the schema, different attribute types, using profiles, etc.
+++++++++
How to determine if a Log or Event is support by OCSF?
Target data is supported in OCSF when the sample matches an appropriate Category/Event Class as well as contains all required attributes. If the sample does not contain required fields, and required value data can not be constructed at parse time, the log is unsupported.
FAQ
How exactly is "supported logs" determined?
A: Sample must contain required fields.
What can I do if the log is unsupported?
A: Work with source data provider and/or OCSF community to add support.
What are some example parsed/translated samples for known data?
A: Sysmon or other common event translated to OCSF <>.
What data format should I use for OCSF?
A. That is an implementation detail that depends upon the target technology. Different vendors might have different format or transfer mechanisms. Work with that vendor to determine.
Currently, the only way to view all the supported data types in OCSF is via a local instance of the ocsf_server. Instead, we should provide an easy access to it by creating a .md file accessible in the repo.
A simple .md file should suffice.
Once created, link this file in the contribution guideline file - line# 66
Thank you for writing such an excellent white paper that introduces the schema so thoroughly. It is incredibly well written and complete. There are a few places where I think that I can contribute (editorially, of course -- I would never presume to change the content) and would love to submit PRs.
I cannot seem to find the right place to do that. In fact, I am sure that using the Issues
in this repo is not even the best place for this message -- I apologize.
I look forward to helping, if I can!
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.