Closed sbarnum closed 1 year ago
@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 Tool
to Tool
or Software
(which I'm pretty much fine with), but then also create an entire namespace devoted to effectively one object. I haven't gone through and parsed your semi-formal language description and I am still addressing other filed proposals, so I don't entirely know the extent of what your sketched solution entails.
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 drafting.ttl
in this directory, to demonstrate its feasibility:
https://github.com/casework/CASE-Examples/tree/master/examples/illustrations/configured_tool
That directory contains a tested transcription of the example in your last comment from 405. If you run make
after writing drafting.ttl
and revising configured_tool.json
, you'll see how well the draft implementation works out.
Eoghan asked for us to try to combine efforts on this. I believe that 405 falls short of what is necessary and that 432 covers all of 405 plus more. More that has been needed for a long while. As such I believe it makes sense to pursue 432 rather than 405 separately. I will work to pull together technical implementation to hopefully clear up any lack of clarity or confusion.
@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.
@sbarnum - correction, this is now the most recent commit. I hadn't added definition comments or rdfs:label
s as I was testing, but they're in that new commit now.
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. I also tried attaching the two files here in case I cannot get git to play well but git does not want to allow ttl or json files.
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:
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). :-(
Two candidate causes:
java -version
tells you that you're on version 11 or newer. This is required in UCO's ecosystem since this issue.rdf-toolkit.jar
at lib/rdf-toolkit.jar
. Basically, if the mtime is older than around 2 weeks ago, you should run these commands, and then run make
again:rm .lib.done.log
rm lib/rdf-toolkit.jar
make clean
had purposefully avoided deleting rdf-toolkit.jar
because it was assumed to be a stable-enough resource that it'd be more harm than good deleting it on every make clean
. You've hit the once-in-about-3-years case where that might not have been true.
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: Product configuration knowledge modeling using ontology web language. Please have a look at how the authors define a general configuration ontology (Section 3.) that -or parts thereof- might be reused.
@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 core:Relationship
as an action:instrument
value, and I also think that his suggested usage of a core:Relationship
is incorrect in the context of defining a configured tool (or software) object. A ConfiguredTool
(/ConfiguredSoftware
) object feels like an inherent object ( @plbt5 likely has a better term for this), in that it does not make sense to describe without the non-configured object. (Paul's usual example here is something like the color of a red car, where the car's redness does not exist if the car does not exist.)
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 ConfiguredX
subclasses.
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.
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 configuration:usesConfiguration
: Should Configuration
objects be shareable?
Suppose a tool version 1.0 releases a version 1.1 with no API or CLI changes. Suppose also a configuration object kb:configuration-1
was used for the configured run of version 1. To you, is this acceptable usage?
[
{
"@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 usesConfiguration
should be declared, and tested as, an owl:InverseFunctionalProperty
, as we had done for core:hasFacet
in Issue 379.
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.
I agree with this combined solution to fulfill the requirements originally articulated in #405 and expanded in #455. Thank you Alex and Sean for working through this together to provide a robust solution.
The range for the itemObject property should be UcoThing to enable expression of structured configuration items.
I will provide an example lateer.
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 UcoObject
. If we're wrong and need to expand, that is a backwards-compatible change. If this were reversed, we would not be able to tighten the constraint from UcoThing
to UcoObject
and call it a backwards-compatible change.
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