-
Notifications
You must be signed in to change notification settings - Fork 34
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add a new Configuration object to support flexible expression of configuration details for tools and software #432
Comments
@sbarnum , this proposal complicates the review process. You were not the one who filed Issue 405, and this issue performs a few expansions - one to "union-expand" the applicability of the configuration from 405, from Unless the proposer for 405 agrees to withdraw that proposal and let this supersede, we will continue with reviewing 405, and treat 432 as an independent follow-on proposal. Rather than ask us to mentally parse your language into mental UML models, I encourage you to draft your proposal in a file That directory contains a tested transcription of the example in your last comment from 405. If you run |
Eoghan asked for us to try to combine efforts on this. |
@sbarnum , I agree at a high level that it would be better for 432 to be pursed. However, I don't have the bandwidth to test 432 in addition to some nuances I thought needed to be explored in 405. 405 has a ready-for-solutions-approval vote PR, 447. If you can build an implementation yourself starting from 447's last commit as a baseline, I'm happy to consider Issue 432 a fast-track proposal. |
I created a branch off of the commit you posted an hour ago and created updated drafting.ttl and configured_tool.json files to align with CP-432. Unfortunately, git is not letting me push the branch back up. |
running make throws an error about rdf-toolkit.jar which I assume is likely something to do with my environment which is never stable (see issues above with git). :-( |
I am going to try to branch and modify the files directly on github using browser and see if that works. |
I am crossing my mental streams between UCO ontology and CASE-Examples. :-( I will simply create a branch of UCO ontology with implementation for 432 |
Re:
Two candidate causes:
rm .lib.done.log
rm lib/rdf-toolkit.jar
|
This branch Feature-Issue-432 was created off your last commit above and contains implementation changes to tool.ttl and adds configuration.ttl |
I found this in literature that can be useful as (part of the) solution: |
This patch is a manual adjustment to apply UCO current ontology spelling and linking practices. * While the `rdfs:label` for the `owl:Ontology` includes the `uco-` prefix on the namespace short form, the prefix encoded in Turtle for concepts has not included the `uco-` prefix. * `rdfs:seeAlso` has been used when drafting ontology concepts in files named `drafting.ttl`, as a part of CASE development practice, to tie the concept to its originating work-anchor (whether Jira ticket, Github Issue, or other). However, by the time concepts migrate into the UCO or CASE ontology Turtle files, `rdfs:seeAlso` is not used to reference originating tickets. The first issue caused a breakage in normalization, because the `@prefix` declaration didn't quite agree with all of the UCO concept references. So, this patch applies the manual spelling changes, and a follow-on patch will normalize the new `configuration.ttl` file. References: * #432 Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>
References: * #432 Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>
Because Sean used seeAlso on a few other properties, I was able to catch a point of development interest. It seems we're moving towards more fleshed-out citations, which I'm happy to support. References: * #432 Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>
This patch is motivated by several matters: 1. This class will be introduced (under another name) in the resolution of Issue 430. So, entailing it in this proposal is a risk to this proposal's acceptance. 2. The semantics of using the higher-class-than-UcoObject are not defined. Under what conditions is it OK to use a `types:Hash` object with this property? What about a `types:Dictionary`, `types:ControlledDictionaryEntry`, or `types:ThreadItem`? References to `core:ClassBase` will be restored (under its agreed-upon name alteration, `core:UcoThing`) only after explanation and demonstration of the semantic issues. References: * #430 * #432 Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>
An `sh:xone` pattern was introduced as part of Issue 405. Sean removed it when migrating concepts over to the new `configuration` namespace, and neither documented why nor updated the unit test that expected it. This patch restores the addition. References: * #405 * #432 Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>
This patch should restore CI passing. A follow-on patch will regenerate Make-managed files. References: * #432 Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>
References: * #432 Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>
This aligns cardinality of `itemValue` with `itemObject`, and permits setting multiple values for a parameter, such as multiple independent filter patterns. References * #432 Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>
Sean removed `tool:ConfiguredTool` and `tool:isConfigurationOf` from the implementation for Issue 405, without explanation. His revised demonstration of how to represent a tool being used with a configuration within an action included this excerpt (not complete UCO JSON-LD, but sufficient to demonstrate the design issue): ```json [ { "@id": "kb:relationship-d6d18770-cb60-4779-b28a-905846dbd3f4", "@type": "uco-core:Relationship", "uco-core:source": "kb:AnalyticTool-DAE5EE58-E5ED-4588-93BE-CDEC6FAA9C6A", "uco-core:target": "kb:Configuration-4bc42c81-e9e7-4f48-b066-17e7fdca0f92", "uco-core:kindOfRelationship": "Has_Configuration", "uco-core:startTime": "2010-01-15T17:59:43.25Z", }, { "@id": "kb:Analysis-7cd51fa7-63ee-4f40-a482-9ce8333c7556", "@type": "uco-analysis:Analysis", "uco-core:name": "compute string similarity", "uco-action:instrument": [ "kb:AnalyticTool-DAE5EE58-E5ED-4588-93BE-CDEC6FAA9C6A", "kb:relationship-d6d18770-cb60-4779-b28a-905846dbd3f4", "kb:Configuration-4bc42c81-e9e7-4f48-b066-17e7fdca0f92" ] } ] ``` `tool:ToolConfigurationTypeFacet` was also removed, and I agree that that is obviated with the `Configuration` class. Because that `Facet` is removed, another mechanism is needed to link a configuration to a `Tool` or a `Software`. This patch restores `ConfiguredTool`, and adds a similar class `ConfiguredSoftware` to meet the expanded objective of Issue 432. `isConfigurationOf` is restored as a more generically-specified property, leaving type-scoping to the SHACL associations. `configuration:usesConfiguration` is added to link a `ConfiguredX` instance to a `Configuration`. With the above new and restored properties and classes, the above JSON-LD snippet is now expressible like this, most notably removing the complexity of references in `action:instrument`: ```json [ { "@id": "kb:configured-tool-c6718138-e953-4731-bf52-d7d89eae9c85", "@type": [ "uco-tool:AnalyticTool", "uco-tool:ConfiguredTool", ], "uco-configuration:isConfigurationOf": "kb:AnalyticTool-DAE5EE58-E5ED-4588-93BE-CDEC6FAA9C6A", "uco-configuration:usesConfiguration": "kb:Configuration-4bc42c81-e9e7-4f48-b066-17e7fdca0f92", "uco-core:objectCreatedTime": "2010-01-15T17:59:43.25Z", }, { "@id": "kb:Analysis-7cd51fa7-63ee-4f40-a482-9ce8333c7556", "@type": "uco-analysis:Analysis", "uco-core:name": "compute string similarity", "uco-action:instrument": "kb:configured-tool-c6718138-e953-4731-bf52-d7d89eae9c85" } ] ``` Tests are updated to exercise the new classes and properties. A follow-on patch will regenerate Make-managed files. References: * #405 * #432 Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>
Issue 430 was presumed in some of the new `sh:nodeKind` specifications. This patch relaxes those to `sh:BlankNodeOrIRI` as used everywhere else in UCO before the passage of 430. Once 430 is passed, this patch will be reverted. References: * #430 * #432 Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>
@plbt5 , with apologies, I have too much release preparation to do to find time to review your suggested material. If you have a summary of the impact of the material that would re-shape the implementation of Issues #405 or this 432, please provide it as a pull request. OCs: I've looked through @sbarnum 's implementation, and found he reverted some of the implementation I had done for 405. The changes are restored, with the largest documentation in this patch. I am significantly concerned with the usage of a The implementation will undergo testing tomorrow, but please weigh in if you have a preference for Sean's pattern (especially referring to his full JSON-LD snippet in the Issue's description) over the The pull request's commits each have a log message documenting the commit's effects. Please refer to any of the commits if you observe an issue. |
No effects were observed on Make-managed files. References: * ucoProject/UCO#432 Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>
A follow-on patch will regenerate Make-managed files. References: * ucoProject/UCO#432 Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>
References: * ucoProject/UCO#432 Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>
A follow-on patch will regenerate Make-managed files. References: * ucoProject/UCO#432 Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>
References: * ucoProject/UCO#432 Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>
A follow-on patch will regenerate Make-managed files. References: * ucoProject/UCO#432 Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>
References: * ucoProject/UCO#432 Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>
A follow-on patch will regenerate Make-managed files. References: * ucoProject/UCO#432 Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>
References: * ucoProject/UCO#432 Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>
OCs: Impact on the CASE examples has been reviewed. The updates that will be necessary in support of the current state of implementation of Issue 432 are best illustrated in these two commits: |
@sbarnum : I did not transcribe your JSON-LD example to CASE-Examples, because it presumed other in-flight proposals (JSON-LD context dictionary, and analysis namespace), some of which have received insufficient development to be scheduled for 1.0.0. |
Question for the OCs, illustrating the "inherent" property Suppose a tool version 1.0 releases a version 1.1 with no API or CLI changes. Suppose also a configuration object [
{
"@id": "kb:tool-v10",
"@type": "tool:Tool"
},
{
"@id": "kb:tool-v11",
"@type": "tool:Tool"
},
{
"@id": "kb:configuration-1",
"@type": "configuration:Configuration"
},
{
"@id": "kb:configured-tool-v10",
"@type": "tool:ConfiguredTool",
"configuration:isConfigurationOf": "kb:tool-v10",
"configuration:usesConfiguration": "kb:configuration-1"
},
{
"@id": "kb:configured-tool-v11",
"@type": "tool:ConfiguredTool",
"configuration:isConfigurationOf": "kb:tool-v11",
"configuration:usesConfiguration": "kb:configuration-1"
}
] If the committee thinks it not acceptable to permit this, then |
I would assert that it is not only desirable but necessary (for correct graph analysis and navigation) for a range of use cases beyond the simple example here, especially for Software (beyond just Tools). Think about things like DISA STIGs or the application space of NIST SP 800-128, etc. |
The range for the itemObject property should be UcoThing to enable expression of structured configuration items. I will provide an example lateer. |
This will need to be done in a later proposal in 1.x.0. I described in the OCs call this morning that we're going into 1.0.0 with this on the tighter constraint of |
This should have happened as part of resolving Issue 432. No effects were observed on Make-managed files. References: * #432 Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>
RDFS and OWL are receiving aliases for in-common spelling in adopters' code. OWL also specifically got further support in some UCO issues. This patch also adds a `Namespace` for the import of the Collections Ontology, and the new UCO namespace `configuration`. References: * ucoProject/UCO#389 * ucoProject/UCO#406 * ucoProject/UCO#432 * ucoProject/UCO#437 Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>
RDFS and OWL are receiving aliases for in-common spelling in adopters' code. OWL also specifically got further support in some UCO issues. This patch also adds a `Namespace` for the import of the Collections Ontology, and the new UCO namespace `configuration`. References: * ucoProject/UCO#389 * ucoProject/UCO#406 * ucoProject/UCO#432 * ucoProject/UCO#437 Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>
Background
This change proposal is an extended revision to CP-405 and should completely replace it.
Need to represent multiple different configurations of the same tool, each referencing the same Tool object. Knowing what tool was run for each different configuration should be represented as a link in the graph, and not rely on the string name value. In addition, tool configuration needs an added property to reference an object that was provided as an argument/input to the Tool (e.g. so you could have a graph-object for NSRL-as-of-March-2022 or ClamAV signature-database version X, and show where in the graph that object had been involved in decision processes).
The need to express configuration details is not unique to Tool.
It is equally relevant to observable:Software.
A flexible and consistent approach is needed to specify configuration details (including literal key/value pair settings as well as more complex object values) in a way that supports both tool and software user cases.
Such an approach should seek to maximize brevity, consistency, and flexiblity while minimizing duplication throughout the UCO ontology.
Requirements
Requirement 1
UCO must be able to represent how a tool or software was configured at the time of its invocation.
Requirement 2
A tool or software configuration that uses an object (such as a file or service endpoint) must be representable similar to the literal-valued tool:itemValue.
Requirement 3
UCO must be able to represent that one too or softwarel was used under multiple configurations.
Requirement 4
UCO must be able to use one tool or software configuration in multiple invocations.
E.g. if a tool analyzer_engine has a configuration involving calling it on the command line with the flag --auto-detect-content-type, and the tool is called once per input file for two input files, those two tool invocations should have their action:instrument objects use the same ConfiguredTool.
Requirement 5
UCO must support looking up when a tool or software is used with a certain flag.
E.g. if a tool analyzer_engine can take the unparameterized (0-argument) command-line flag --auto-detect-content-type, a UCO graph should be reviewable for when analyzer_engine is configured to use that flag, and in what action:Actions that configuration was used.
Requirement 6
UCO must support looking up when a tool or software is used with a certain flag-value. This applies to object-values (such as a file or service end-point reference), and literal-values (such as a string).
E.g. if a tool analyzer_engine can take the parameterized (1-argument) command-line flag --assume-content-type, a UCO graph should be reviewable for when analyzer_engine is configured to use that flag, and in what action:Actions that configuration was used.
Requirement 7
One tool used in multiple configurations should be linkable between those configurations and the actions using those configurations.
Risk / Benefit analysis
Benefits
Permit flexible representation of various configurations of tools and software.
Permit representation of multiple different configurations of the same tool or software, while maintaining link to the same Tool or Software
Risks
The submitter is unaware of risks associated with this change.
Competencies demonstrated
Competency 1
When a single tool or software is used in a workflow with multiple configuration sections, determine which Tool was used to obtain all observables, independent of all different tool configurations used.
Competency Question 1.1
What Tool or Software was used to obtain all observables?
Result 1.1
Query returns a single result Tool or Software.
Competency 2
A version of a tool or software known to contain a defect or vulnerability should be locatable within a graph, to understand the impact of results.
Competency Question 2.1
What Tool or Software was used to obtain all observables?
Result 2.1
Query returns all results affected by the defect or vulnerability.
Competency Question 2.2
A Software version 1.0 is known to have a vulnerability. What related devices or systems may be vulnerable do to the Software under any configuration.
Result 2.2
Query returns all related objects that may be vulnerable due to their relationship with the affected Software.
Competency 3
When different versions of a resource (e.g., NSRL hashset, AntiVirus database) were provided in various Tool Configuration objects, determine which resource was provided as an argument to a given Tool Configuration object.
Competency Question 3.1
What resource was referenced in the itemObject property of a given Tool Configuration object?
Result 3.1
Query returns a single object that was referenced in the itemObject of the given Tool Configuration object.
Solution suggestion
Additions
Modifcations
Deletions
Examples
Example of an Action using a Tool with a Configuration
Example of Multiple Actions each using a Tool with different Configurations
Example of a Software with a Configuration
Coordination
develop
The text was updated successfully, but these errors were encountered: