Docs: Add nibble documentation #3983
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
|
Great work @stephanie0x00, I made some suggestions to make the work even better :) |
ammar92
reviewed
Dec 24, 2024
There was a problem hiding this comment.
Nice work! This definitely helps in understanding Nibbles 👍
A few general things:
- We should capitalize Bits and Nibbles, as they refer to our modules and not the data units
- Use cross-references for linking to our own documentation, this is a safer method and results in less broken links
- The Octopoes page is getting quite big, we should consider splitting it up in smaller chunks
- Not for now per se, but we should prefer the reST syntax over Markdown as it's much more flexible and offer more tools
Maybe we can have some coffee together soon and discuss some docs related stuff?
| ## Nibbles | ||
|
|
||
| **What are nibbles?** | ||
| Nibbles are the flexible replacement for bits. We learned a lot on what does and doesn't work around bits and ran into some limitations. The nibbles are solving these limitations. We hope that the nibbles are 4 times as efficient as bits, but this isn't officially bench marked (and is more of a bits-nibbles joke ;)). |
There was a problem hiding this comment.
Suggested change
| Nibbles are the flexible replacement for bits. We learned a lot on what does and doesn't work around bits and ran into some limitations. The nibbles are solving these limitations. We hope that the nibbles are 4 times as efficient as bits, but this isn't officially bench marked (and is more of a bits-nibbles joke ;)). | |
| Nibbles are the flexible replacement for bits. We learned a lot on what does and doesn't work around bits and ran into some limitations. The nibbles are solving these limitations. We hope that the nibbles are 4 times as efficient as bits, but this isn't officially benchmarked (and is more of a bits-nibbles joke ;)). |
| **What are nibbles?** | ||
| Nibbles are the flexible replacement for bits. We learned a lot on what does and doesn't work around bits and ran into some limitations. The nibbles are solving these limitations. We hope that the nibbles are 4 times as efficient as bits, but this isn't officially bench marked (and is more of a bits-nibbles joke ;)). | ||
|
|
||
| Nibbles process the data in OpenKAT, they correlate data and try to extract as much information as possible based on the specified rules. Nibbles ensure for a mapping of one or more objects to another bunch of objects. Where bits would trigger on objects, nibbles can trigger on sets of objects. This makes it possible to map a single object to N objects (1 to N objects), but also map multiple objects to multiple objects (N to N objects). |
There was a problem hiding this comment.
Suggested change
| Nibbles process the data in OpenKAT, they correlate data and try to extract as much information as possible based on the specified rules. Nibbles ensure for a mapping of one or more objects to another bunch of objects. Where bits would trigger on objects, nibbles can trigger on sets of objects. This makes it possible to map a single object to N objects (1 to N objects), but also map multiple objects to multiple objects (N to N objects). | |
| Nibbles process the data in OpenKAT, they correlate data and try to extract as much information as possible based on the specified rules. Nibbles ensure for a mapping of one or more objects to another group of objects. Where bits would trigger on objects, nibbles can trigger on sets of objects. This makes it possible to map a single object to N objects (1-to-N mapping), but also map multiple objects to multiple objects (N-to-N mapping). |
|
|
||
| Nibbles process the data in OpenKAT, they correlate data and try to extract as much information as possible based on the specified rules. Nibbles ensure for a mapping of one or more objects to another bunch of objects. Where bits would trigger on objects, nibbles can trigger on sets of objects. This makes it possible to map a single object to N objects (1 to N objects), but also map multiple objects to multiple objects (N to N objects). | ||
|
|
||
| **Limitation example of bits** |
There was a problem hiding this comment.
Suggested change
| **Limitation example of bits** | |
| **Limitation example of Bits** |
| **Limitation example of bits** | ||
| One of the limitations from bits was that if one of the bits (business rules) would identify an open port in network A, and for network B this port would identify as closed, how would you classify the port? With bits it was not possible to correctly identify data mismatches and decide upon this. Nibbles allow you to detect these differences in data observations. If there are any inconsistencies, this could other nibbles to be triggered to resolve the inconsistency. | ||
|
|
||
| **How are nibbles better than bits?** |
There was a problem hiding this comment.
Suggested change
| **How are nibbles better than bits?** | |
| **How are nibbles better than Bits?** |
| Nibbles process the data in OpenKAT, they correlate data and try to extract as much information as possible based on the specified rules. Nibbles ensure for a mapping of one or more objects to another bunch of objects. Where bits would trigger on objects, nibbles can trigger on sets of objects. This makes it possible to map a single object to N objects (1 to N objects), but also map multiple objects to multiple objects (N to N objects). | ||
|
|
||
| **Limitation example of bits** | ||
| One of the limitations from bits was that if one of the bits (business rules) would identify an open port in network A, and for network B this port would identify as closed, how would you classify the port? With bits it was not possible to correctly identify data mismatches and decide upon this. Nibbles allow you to detect these differences in data observations. If there are any inconsistencies, this could other nibbles to be triggered to resolve the inconsistency. |
There was a problem hiding this comment.
Suggested change
| One of the limitations from bits was that if one of the bits (business rules) would identify an open port in network A, and for network B this port would identify as closed, how would you classify the port? With bits it was not possible to correctly identify data mismatches and decide upon this. Nibbles allow you to detect these differences in data observations. If there are any inconsistencies, this could other nibbles to be triggered to resolve the inconsistency. | |
| One of the limitations from Bits was that if one of the bits (business rules) would identify an open port in network A, and for network B this port would identify as closed, how would you classify the port? With Bits it was not possible to correctly identify data mismatches and decide upon this. Nibbles allow you to detect these differences in data observations. If there are any inconsistencies, this could other nibbles to be triggered to resolve the inconsistency. |
| One of the limitations from bits was that if one of the bits (business rules) would identify an open port in network A, and for network B this port would identify as closed, how would you classify the port? With bits it was not possible to correctly identify data mismatches and decide upon this. Nibbles allow you to detect these differences in data observations. If there are any inconsistencies, this could other nibbles to be triggered to resolve the inconsistency. | ||
|
|
||
| **How are nibbles better than bits?** | ||
| Nibbles are a successor for bits, all the mistakes and issues we learned from bits should be solved with nibbles. |
There was a problem hiding this comment.
Suggested change
| Nibbles are a successor for bits, all the mistakes and issues we learned from bits should be solved with nibbles. | |
| Nibbles are a successor for bits, all the mistakes and issues we learned from Bits should be solved with nibbles. |
| Nibbles are a successor for bits, all the mistakes and issues we learned from bits should be solved with nibbles. | ||
|
|
||
| - Dynamic loading from the user interface. This allows a user to enable, run or add nibbles from the web interface, instead of having to edit the code. | ||
| - Mapping of objects: bits would trigger if a specific object (ooi) was loaded. This required a lot of recalculation of bits, which is not cost effective. With nibbles, as soon as data is added to the XTDB database, the nibbles will pick this up and handle accordingly. This should speed things up and allows for more extensive querying. |
There was a problem hiding this comment.
Suggested change
| - Mapping of objects: bits would trigger if a specific object (ooi) was loaded. This required a lot of recalculation of bits, which is not cost effective. With nibbles, as soon as data is added to the XTDB database, the nibbles will pick this up and handle accordingly. This should speed things up and allows for more extensive querying. | |
| - Mapping of objects: Bits would trigger if a specific object (ooi) was loaded. This required a lot of recalculation of Bits, which is not cost effective. With nibbles, as soon as data is added to the XTDB database, the nibbles will pick this up and handle accordingly. This should speed things up and allows for more extensive querying. |
Comment on lines
+457
to
+459
| Nibbles are the flexible replacement for bits. We learned a lot on what does and doesn't work around bits and ran into some limitations. The nibbles are solving these limitations. We hope that the nibbles are 4 times as efficient as bits, but this isn't officially bench marked (and is more of a bits-nibbles joke ;)). | ||
|
|
||
| Nibbles process the data in OpenKAT, they correlate data and try to extract as much information as possible based on the specified rules. Nibbles ensure for a mapping of one or more objects to another bunch of objects. |
There was a problem hiding this comment.
Suggested change
| Nibbles are the flexible replacement for bits. We learned a lot on what does and doesn't work around bits and ran into some limitations. The nibbles are solving these limitations. We hope that the nibbles are 4 times as efficient as bits, but this isn't officially bench marked (and is more of a bits-nibbles joke ;)). | |
| Nibbles process the data in OpenKAT, they correlate data and try to extract as much information as possible based on the specified rules. Nibbles ensure for a mapping of one or more objects to another bunch of objects. | |
| Nibbles are the flexible replacement for Bits. We learned a lot on what does and doesn't work around Bits and ran into some limitations. The nibbles are solving these limitations. We hope that the nibbles are 4 times as efficient as bits, but this isn't officially benchmarked (and is more of a bits-nibbles joke ;)). | |
| Nibbles process the data in OpenKAT, they correlate data and try to extract as much information as possible based on the specified rules. Nibbles ensure for a mapping of one or more objects to another group of objects. |
|
|
||
| Nibbles process the data in OpenKAT, they correlate data and try to extract as much information as possible based on the specified rules. Nibbles ensure for a mapping of one or more objects to another bunch of objects. | ||
|
|
||
| A more technical explanation on Nibbles can be found at: `https://docs.openkat.nl/developer-documentation/octopoes.html#nibbles <https://docs.openkat.nl/developer-documentation/octopoes.html#nibbles>`_. |
There was a problem hiding this comment.
Please do not link to external sources, use cross-reference links as documented here
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Changes
This PR adds documentation to docs.openkat.nl on what nibbles are and why they replace bits.
Issue link
Closes #3976
Demo
n/a
QA notes
Check if what is written is correct on how nibbles work and if you actually understand what nibbles are now. This is currently still a work in progress while nibbles are further developed.
Code Checklist
.envchanges files if required and changed the.env-distaccordingly.Checklist for code reviewers:
Copy-paste the checklist from the docs/source/templates folder into your comment.
Checklist for QA:
Copy-paste the checklist from the docs/source/templates folder into your comment.