Re: [cti-users] Java STIX 2.x Libary

[Stephen Russett <stephen@digitalstate.ca>]

Good afternoon all!

Wanted to share a nice update for the Java Stix Library.

Rollout of immutables and full JSON Serialization/Deserialization has been completed.

As mentioned, you get builds with full spec logic coverage and nice âwith*()â methods allowing you to create a new version of the immutable with the addition N properties. Âsuch as:

AttackPattern attackPattern123 = AttackPattern.builder()
        .name("Some Attack Pattern 1")
        .build()

AttackPattern someNewAttackPattern = attackPattern123.withKillChainPhases(KillChainPhase.builder()
        .killChainName("Some Name")
        .phaseName("Some Phase")
        .build())

âsomeNewAttackPatternâ is a full copy + the new KillChain information added. All methods match the properties defined in the spec.

Here is a more complex example of usage from Generation of objects, generation of JSON, and parsing json back objects. Note how you do not need to know/enforce which type of object you are parsing, the parser will figure it out based on the Type and IDs, validate it, and return the needed info.

class BundleSpec extends Specification {

    def "Basic 'uses' Relationship object and addition to bundle"(){
        when: "Create a Relationship with Attack Pattern and Malware"

        Relationship usesRel = Relationship.builder()
                .relationshipType("uses")
                .created(Instant.now())
                .sourceRef(AttackPattern.builder()
                        .name("Some Attack Pattern 1")
                        .build())
                .targetRef(Malware.builder()
                        .name("dog")
                        .addLabels("worm")
                        .build())
                .build()

        then: "print the JSON string version of the created relationship object"
        println usesRel.toJsonString()

        then: "parse the string back into a relationship object"
        BundleableObject parsedRelationship = StixParsers.parseBundleableObject(usesRel.toJsonString())
        assert parsedRelationship instanceof Relationship

        Relationship typedRelation = (Relationship)parsedRelationship

        and: "print the parsed relation"
        println typedRelation

        then: "ensure the original JSON matches the new JSON"
        assert usesRel.toJsonString() == typedRelation.toJsonString()

        then: "add the relationship into a bundle"
        Bundle bundle = Bundle.builder()
                .addObjects(usesRel)
                .build()

        and: "print the bundle json"
        println bundle.toJsonString()

        then: "parse json bundle back into object"
        BundleObject parsedBundle = StixParsers.parseBundle(bundle.toJsonString())
        assert parsedBundle instanceof Bundle
        Bundle typedBundle = (Bundle)parsedBundle

        then: "ensure original bundle and parsed bundles match in their json forms"
        assert bundle.toJsonString() == typedBundle.toJsonString()

    }

    def "bundleable object parsing"(){
        when: "setup parser and object"
        String attackPatternString = AttackPattern.builder()
                                        .name("Some Attack Pattern 1")
                                        .build().toJsonString()

        then: "can parse the json back into a attack Pattern"
        BundleableObject parsedAttackPatternBo = StixParsers.parseBundleableObject(attackPatternString)
        assert parsedAttackPatternBo instanceof AttackPattern

        AttackPattern parsedAttackPattern = (AttackPattern)StixParsers.parseBundleableObject(attackPatternString)
        println parsedAttackPattern.toJsonString()
        
    }
}

Enjoy!!

From:ÂStephen Russett <stephen@digitalstate.ca>
Reply:ÂStephen Russett <stephen@digitalstate.ca>
Date:ÂDecember 5, 2018 at 2:33:06 PM
To:Âcti-users@lists.oasis-open.org <cti-users@lists.oasis-open.org>
Subject:Â Re: [cti-users] Java STIX 2.x Libary

Hey Everyone

just little update for the java lib.

I have started cleanup refactor now that all of the angles were generally covered.

All of the objects have been implemented as Immutable and you get a nice builder interface for everything:

when:
Relationship derived = Relationship.builder()
        .relationshipType("derived-from")
        .sourceRef(AttackPattern.builder()
                .name("Some Attack Pattern 1")
                .build())
        .targetRef(AttackPattern.builder()
                .name("Some Other Attack Patter 2")
                .build())
        .build()

Bundle stixBundleObject = Bundle.builder()
        .addObjects(derived)
        .build()

There are lots of helper methods that come with the builders as well, allowing you to transfer from one Immutable to another. ÂAll objects support two modes of Hydration: dehydrated: Type+ID or Hydrated: normal attribute requirements. With dehydrated this is a object that only contains a type and a Id (such as when deserializing a object with a relationship). A interesting factor here is the easy ability extend this to any fields and add additional layers, as its all enforced with validation groups:Â

@NotBlank(groups = {Default.class, ValidateIdOnly.class}, message = "Type is required")
@JsonProperty("type")
default String getType(){
    return typeValue();
}

vs another attribute such as:

@NotNull
@JsonProperty("created")
@Value.Default
default Instant getCreated(){
    return Instant.now();
}

The example above allows anyone to easily extend or configure hydration or dehydrated attribute requirements with a singleÂgroups = {Default.class, ValidateIdOnly.class}

Âwhich says âenforce this validation for the Default group and the ValidateIdOnlyGroup. When no group is provided the default group enforcement is used.

You also get Annotation validators, allowing really easy extension:

So consider where Malware SDO reuses the Labels but enforces (or with a âSHOULDâ) of a specific vocabulary:

you get to use Annotations!

@Override
@Vocab(MalwareLabels.class)
@NotNull @Size(min = 1, message = "At least one label from malware-label-ov must be used")
Set<@Size(min = 1) String> getLabels();

@Vocab can be used on Strings and on Sets of Strings. ÂAllowing default and custom vocab usage. There is also Â@RelationshipTypeLimit

@RelationshipTypeLimit(source = MalwareSdo.class, relationshipTypes = {"targets", "uses", "variant-of"})

This can be applied on a Class to enforce a Relationshipâs relationshipTypes based on the Source SDO.

and then there is @RelationshipLimit:

@RelationshipLimit(source = MalwareSdo.class, relationshipType = "targets", target = {IdentitySdo.class, VulnerabilitySdo.class})
@RelationshipLimit(source = MalwareSdo.class, relationshipType = "uses", target = {ToolSdo.class})
@RelationshipLimit(source = MalwareSdo.class, relationshipType = "variant-of", target = {MalwareSdo.class})

or:Â

@RelationshipLimit(source = DomainObject.class, relationshipType = "derived-from", target = {DomainObject.class}, classEquality = true)

This allows you to defined Target-ref restrictions for relationship Types and Source SDOs.

Enjoy!

From:ÂStephen Russett <stephen@digitalstate.ca>
Reply:ÂStephen Russett <stephen@digitalstate.ca>
Date:ÂNovember 29, 2018 at 8:48:11 PM
To:Âcti-users@lists.oasis-open.org <cti-users@lists.oasis-open.org>
Subject:Â Re: [cti-users] Java STIX 2.x Libary

Hey everyone

just update on the lib: All of the spec has been added minus the cyber observables and pattern checking support.

I am now adding unit tests to ensure full coverage of the spec and everything works well.

Lots of helpers as well such as AttackPattern myAP = AttackPattern.parse(someJsonString). Â.parse() can be used on all objects including a bundle.

and the ability to autopopulate the bundle based on relationships: example the attack pattern has a âtargetsâ or a related_to. Âauto-populate will detect any linked objects and add them to the bundle.

In the same light, there is also âauto-hydrationâ, which is used to populate a object with actual pointers to objects rather than just the string of the ID.

This has interesting use cases for bundle processing: where each object is processed into a java object and then you âhydrateâ the objects where each java object will look back in the bundle of java objects so it can set the links between objects. This same function can also be used when processing STIX data to allow data enrichment: Allowing someone to receive a bundle that has relationships/Ids but not the objects for those Ids. You can use the hydration hooks to look up the Ids in another system(s) to populate the java object.

If anyone has some common issues they run into for stix data quality issues, I would be interested to hear them, so i can cover it in the tests and add helpers to prevent the errors or âauto-correctâ them.

Thanks!

Steve

From:ÂStephen Russett <stephen@digitalstate.ca>
Reply:ÂStephen Russett <stephen@digitalstate.ca>
Date:ÂNovember 22, 2018 at 5:38:24 PM
To:Âcti-users@lists.oasis-open.org <cti-users@lists.oasis-open.org>
Subject:Â Re: [cti-users] Java STIX 2.x Libary

Hi All!

I have just added support for relationships with STIX in the Java lib.

example

```

{

 "type": "bundle",

 "id": "bundle--f428f07f-4efe-4980-9f47-74d946826c69",

 "spec_version": "2.0",

 "objects": [

  {

   "type": "attack-pattern",

   "id": "attack-pattern--cb3010c8-f36c-4dc3-bf3d-8c1ffeb5e1cf",

   "created": "2018-11-22T22:26:43.159Z",

   "modified": "2018-11-25T22:26:43.159Z",

   "revoked": false,

   "object_marking_refs": [

    "marking-definition--6139cfd0-7d2f-4389-b7e3-e97836888268"

   ],

   "granular_markings": [

    {

     "selectors": [

      "pattern1",

      "pattern2",

      "pattern3"

     ],

     "marking_ref": "marking-definition--b4ab8f5b-f812-49c5-a2b2-b168a0ba236d"

    }

   ],

   "name": "some pattern",

   "kill_chain_phases": [

    {

     "kill_chain_name": "Chain1",

     "phase_name": "phase1"

    },

    {

     "kill_chain_name": "Chain1",

     "phase_name": "phase2"

    }

   ],

   "x_someCustomKey": "My custom value",

   "x_someOtherCustom_key": 3939

  },

  {

   "type": "observed-data",

   "id": "observed-data--e3d14217-fc58-47bb-b5fb-b67d6ca78db3",

   "created": "2018-11-22T22:26:43.221Z",

   "modified": "2018-11-22T22:26:43.221Z",

   "revoked": false,

   "object_marking_refs": [

    "marking-definition--39ceb120-7777-4e13-888e-95efb6c99a31"

   ],

   "first_observed": "2018-11-22T22:26:43.209Z",

   "last_observed": "2018-11-22T22:26:43.209Z",

   "number_observed": 3,

   "objects": {

    "some artifact": {

     "type": "artifact",

     "url": "someURL"

    },

    "some AS": {

     "type": "autonomous-system",

     "number": 5,

     "rir": "someRIR"

    }

   }

  },

  {

   "type": "marking-definition",

   "id": "marking-definition--39ceb120-7777-4e13-888e-95efb6c99a31",

   "created": "2018-11-22T22:26:43.208Z",

   "granular_markings": [

    {

     "selectors": [

      "marking-pattern1",

      "pattern2",

      "pattern3"

     ],

     "marking_ref": "marking-definition--b4ab8f5b-f812-49c5-a2b2-b168a0ba236d"

    }

   ],

   "definition_type": "statement",

   "definition": {

    "statement": "Internal review of data allows for sharing as per ABC-009 Standard"

   }

  },

  {

   "type": "marking-definition",

   "id": "marking-definition--b4ab8f5b-f812-49c5-a2b2-b168a0ba236d",

   "created": "2018-11-22T22:26:43.199Z",

   "definition_type": "tlp",

   "definition": {

    "tlp": "red"

   }

  },

  {

   "type": "relationship",

   "id": "relationship--fb64d173-3478-4eb9-abae-c580cf92454c",

   "created": "2018-11-22T22:26:43.242Z",

   "modified": "2018-11-22T22:26:43.242Z",

   "revoked": false,

   "relationship_type": "targets",

   "source": "attack-pattern--cb3010c8-f36c-4dc3-bf3d-8c1ffeb5e1cf",

   "target": "identity--16b669a9-91ef-492d-852c-9249695a09f4"

  }

 ]

}

```

I am hoping some of the community can provide some interesting âcomplexitiesâ for relationships for me to test again. ÂIf you have some scenarios of complexity please share!

All of the relationships are typed checked and validated per SDO. So it should generated fully spec compliant relationships.

as a extra helper to maintain sanity I have added the "bundle.autoDetectBundleObjects()â method. This will traverse the nested relationships and objects inside of each objects in the bundle and add any nested content into the bundle at the parent level as per the spec. The âsanityâ aspect is that if you are building a complex object with many relationships and nested objects, you can build these all inline without the need to generate them as individual bundle items. So you could have a âattack-patternâ with 5 ârelated-toâ, 5 object markings, and 5 granular markings. Âyou would just have to write âbundle.addObjects(myAttackPattern)â and run the âbundle.autoDetectBundleObjects()â method, and it will detect all of the nested 15 objects and add them into the bundle as per the spec.

Thanks

From:ÂTrey Darley <trey@kingfisherops.com>
Reply:ÂTrey Darley <trey@kingfisherops.com>
Date:ÂNovember 21, 2018 at 5:50:17 PM
To:ÂStephen Russett <stephen@digitalstate.ca>
Cc:Âcti-users@lists.oasis-open.org <cti-users@lists.oasis-open.org>
Subject:Â Re: [cti-users] Java STIX 2.x Libary

On 21.11.2018 12:06:54, Stephen Russett wrote:
>
> Wanted to share this project I have been working on that provides a
> few different CTI management tooling, but importantly for this list:
> a STIX 2.x Java library.
>

Nice work, Stephen! Thank you for your efforts on behalf of the wider
CTI community. ^_^

--
Cheers,
Trey Darley
Co-chair, CTI TC
++--------------------------------------------------------------------------++
mobile: +32/494.766.080
gpg fingerprint: 85F3 5F54 4A2A B4CD 33C4 5B9B B30D DD6E 62C8 6C1D
++--------------------------------------------------------------------------++
--
"When you choose the lesser of two evils, always remember that it is
still an evil." --Max Lerner