springzen / java-stix

Java bindings for STIX

java-stix

The Java bindings for STIX, the Structured Threat Information eXpression language used for representing structured cyber threat information.

java-stix is being developed under the official STIXProject

For more information, see http://stix.mitre.org/.

Overview

A primary goal of java-stix is to remain faithful to both the STIX specifications and customary Java practices. java-stix is designed to be intuitive both to Java developers and JAXB XML developers, provide convenience methods to the XJC generated JAXB model, but obviously is not a one-for-one replacement for the python-stix API.

Versioning

Releases of java-stix will comply with the Semantic Versioning specification at http://semver.org/. Java-stix is currently under active development; see TODO.txt for a tentative roadmap. Releases will be announced on the STIX discussion list. A java-stix for a particular schema release will match the STIX schema version in Semantic Versioning form. Follow up patches of java-stix for a particular schema release will increment a 4th digit. For example, the first patch release for java-stix v1.2.0 would be v1.2.0.1. Patches will be worked in a branch prior to being tagged and released.

Releases

Releases are distributed via the Maven Central Repository.

Apache Maven:

<dependency>
  <groupId>org.mitre</groupId>
  <artifactId>stix</artifactId>
  <version>1.2.0.2</version>
</dependency>

Gradle:

compile 'org.mitre:stix:1.2.0.2'

Apache Ivy:

<dependency org="org.mitre" name="stix" rev="1.2.0.2" />

Snapshots

Snapshots are being pushed to

https://oss.sonatype.org/content/repositories/snapshots/org/mitre/stix/

Users using Apache Maven for example can simply retrieve java-stix directly via the Central Repository:

 <repositories>
   <repository>
     <id>snapshots-repo</id>
     <url>https://oss.sonatype.org/content/repositories/snapshots</url>
     <releases><enabled>false</enabled></releases>
     <snapshots><enabled>true</enabled></snapshots>
   </repository>
 </repositories>

<dependencies>
	<dependency>
		<groupId>org.mitre</groupId>
		<artifactId>stix</artifactId>
		<version>1.2.0.2-SNAPSHOT</version>
	</dependency>
</dependencies>

Release artifacts appear in the Maven Central Repository.

Building

java-stix builds under Java7, and Java8.

Clone the repository

Clone the java-stix project via:

git clone https://github.com/STIXProject/java_stix.git

A git clone command will not retrieve schemas project automatically, but the Gradle build script will attempt to retrieve them on execution.

Alternatively, using the --recursive flag when cloning the repository will automatically initialize and update the schema submodules via:

git clone --recursive https://github.com/STIXProject/java_stix.git    

Using the Gradle Wrapper

This project uses a Gradle build script. The project comes with a Gradle Wrapper, a batch script on Windows, and a shell script for UNIX platforms including OS X thereby removing the need to have Gradle installed.

For a UNIX platform, you can run Gradle from the project root via:

./gradlew -x signArchives

This documentation centers on UNIX-centric Gradle command-line execution for brevity, but if you are on Windows you can run Gradle via:

.\gradlew.bat -x signArchives

Executing the tasks Gradle task will inform you of all the tasks runnable from root project like so:

./gradlew tasks

I'd advise using the Gradle command-line, but if you're using the Eclipse IDE consider installing the latest Gradle IDE Pack. Gradle Eclipse integration is somewhat emergent. or if you're using Netbeans consider using Nodeclipse/Enide Gradle for Eclipse.

Retrieving the schemas

If the schemas are not present, the Gradle build script will attempt to retreive and patch the schemas for you, but if it cannot for some reason you will need to retrieve them yourself.

Gradle will execute either the retrieve_schemas.sh shell script or the retreieve_schemas.bat batch script as appopriate for your platform. You can find these in the root of the project, and try executing them yourself or you can follow the steps enumerated in the next section for retrieving the schemas.

Afterward, the cybOX schemas are patched for the flaw described in cybOX Schema issue #340. Until the issue is resolved please be aware of the patch. The patch is found at the root of the project.

Re-retrieving the schemas

If you should need to re-retrieve the schemas have the Gradle build script do it for you:

./gradlew cleanSchema

Then build as normal.

The STIX schemas

To manually retrieve the schemas, enter the project and run these additonal git commands on the command line:

git submodule init
git submodule update --force
cd src/main/resources/schemas/v1.2.0
git checkout tags/v1.2.0

Your not done. You'll also need to retrieve the CybOX schemas.

The CybOX schemas

While in the project:

cd src/main/resources/schemas/v1.2.0
git submodule init
git submodule update --force
cd cybox
git checkout 97beb32c376a9223e91b52cb3e4c8d2af6baf786

When Gradle build script first runs it will also patch the CybOX schemas so that the JAXB2 Simple Document Object Model can be generated. Once patched, it will remained patched locally. If Gradle fails to retrieve the schemas, you will need to patch the schemas by hand from the command-line. The patch file, cybox_object_archive_object_patch is in the root of the project. NetBeans can also apply patches via Team -> Patches -> Apply Diff Patch.

Creating the JAXB2 Document Object Model

Building

It is really unnecessary to build by hand, if your intention is to use the java-stix in your project as snapshot exist in the Maven Central Snapshot repository, and soon releases will exist too.

If you have not set up the signing properties you can instruct Gradle to skip signing jars by doing the following:

./gradlew -x signArchives

After the Gradle wrapper shell script has downloaded and cached the Gradle binary distribution, a successful build will look like something like this on UNIX:

➜  java_stix git:(master) ✗ ./gradlew -x signArchives
:buildSrc:compileJava UP-TO-DATE
:buildSrc:compileGroovy UP-TO-DATE
:buildSrc:processResources UP-TO-DATE
:buildSrc:classes UP-TO-DATE
:buildSrc:jar UP-TO-DATE
:buildSrc:assemble UP-TO-DATE
:buildSrc:compileTestJava UP-TO-DATE
:buildSrc:compileTestGroovy UP-TO-DATE
:buildSrc:processTestResources UP-TO-DATE
:buildSrc:testClasses UP-TO-DATE
:buildSrc:test UP-TO-DATE
:buildSrc:check UP-TO-DATE
:buildSrc:build UP-TO-DATE
:clean
:retrieveSchemas
    Schemas are present. Retrieval is not needed.
    /Users/walsh/Development/workspace/java_stix/src/main/resources/schemas/v1.2.0/cybox/objects/Archive_File_Object.xsd already patched.
:createPrefixNamespaceBindings
    schemas/v1.2.0/external/open_ioc_2010/ioc.xsd claims the same prefix "tns" as schemas/v1.2.0/external/open_ioc_2010/ioc-TR.xsd
:generateJAXB
    Generating JAXB model to /Users/walsh/Development/workspace/java_stix/src/generated/java for STIX Schema v1.2.0 found in /Users/walsh/Development/workspace/java_stix/src/main/resources/schemas/v1.2.0
:generatedSourceTransformation
:createPackageInfo
:compileJava
warning: [options] bootstrap class path not set in conjunction with -source 1.7
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.
1 warning
:compileGroovy UP-TO-DATE
:processResources
:classes
:jar
:javadoc
/Users/walsh/Development/workspace/java_stix/src/generated/java/org/w3/_2000/_09/xmldsig/ObjectFactory.java:277: warning - Tag @link: reference not found: byte[]
/Users/walsh/Development/workspace/java_stix/src/generated/java/org/w3/_2000/_09/xmldsig/ObjectFactory.java:361: warning - Tag @link: reference not found: byte[]
/Users/walsh/Development/workspace/java_stix/src/generated/java/org/w3/_2000/_09/xmldsig/ObjectFactory.java:341: warning - Tag @link: reference not found: byte[]
/Users/walsh/Development/workspace/java_stix/src/generated/java/org/w3/_2000/_09/xmldsig/ObjectFactory.java:311: warning - Tag @link: reference not found: byte[]
/Users/walsh/Development/workspace/java_stix/src/generated/java/org/w3/_2000/_09/xmldsig/ObjectFactory.java:331: warning - Tag @link: reference not found: byte[]
/Users/walsh/Development/workspace/java_stix/src/generated/java/org/w3/_2000/_09/xmldsig/ObjectFactory.java:277: warning - Tag @link: reference not found: byte[]
/Users/walsh/Development/workspace/java_stix/src/generated/java/org/w3/_2000/_09/xmldsig/ObjectFactory.java:311: warning - Tag @link: reference not found: byte[]
/Users/walsh/Development/workspace/java_stix/src/generated/java/org/w3/_2000/_09/xmldsig/ObjectFactory.java:331: warning - Tag @link: reference not found: byte[]
/Users/walsh/Development/workspace/java_stix/src/generated/java/org/w3/_2000/_09/xmldsig/ObjectFactory.java:341: warning - Tag @link: reference not found: byte[]
/Users/walsh/Development/workspace/java_stix/src/generated/java/org/w3/_2000/_09/xmldsig/ObjectFactory.java:361: warning - Tag @link: reference not found: byte[]
/Users/walsh/Development/workspace/java_stix/src/generated/java/org/w3/_2000/_09/xmldsig/SPKIData.java:115: warning - Tag @link: reference not found: byte[]
/Users/walsh/Development/workspace/java_stix/src/generated/java/org/w3/_2000/_09/xmldsig/X509Data.java:132: warning - Tag @link: reference not found: byte[]
/Users/walsh/Development/workspace/java_stix/src/generated/java/org/w3/_2000/_09/xmldsig/X509Data.java:132: warning - Tag @link: reference not found: byte[]
/Users/walsh/Development/workspace/java_stix/src/generated/java/org/w3/_2000/_09/xmldsig/X509Data.java:132: warning - Tag @link: reference not found: byte[]
/Users/walsh/Development/workspace/java_stix/src/generated/java/org/w3/_2000/_09/xmldsig/ObjectFactory.java:277: warning - Tag @link: reference not found: byte[]
/Users/walsh/Development/workspace/java_stix/src/generated/java/org/w3/_2000/_09/xmldsig/ObjectFactory.java:361: warning - Tag @link: reference not found: byte[]
/Users/walsh/Development/workspace/java_stix/src/generated/java/org/w3/_2000/_09/xmldsig/ObjectFactory.java:341: warning - Tag @link: reference not found: byte[]
/Users/walsh/Development/workspace/java_stix/src/generated/java/org/w3/_2000/_09/xmldsig/ObjectFactory.java:311: warning - Tag @link: reference not found: byte[]
/Users/walsh/Development/workspace/java_stix/src/generated/java/org/w3/_2000/_09/xmldsig/ObjectFactory.java:331: warning - Tag @link: reference not found: byte[]
19 warnings
:javadocJar
:sourcesJar
:assemble
:compileTestJava UP-TO-DATE
:compileTestGroovy
:processTestResources
:testClasses
:test
:check
:build

BUILD SUCCESSFUL

Total time: 3 mins 45.121 secs

Ignore the javadoc tag warnings they have no impact on the build. Also, ignore the warning about unchecked or unsafe operations as they are an artifact of XJC being used to autogenerate the document object model.

If you want more detail consider passing -d/--debug or -i/--info along with --stacktrace on the command line like so:

./gradlew -x signArchives --stacktrace --debug

for a more detailed build. I set an environment CI_OPTS variable with this value for CircleCi builds to be bettered informed as to why the buiid is failing. Travis CI apparently cano't handle running in debug. So if you want see this level of build detail, click on the CircelCi badge for at the top of this readme.

If the build goes well you will find the jars:

build/libs/stix-${version}.jar
build/libs/stix-${version}-javadoc.jar 
build/libs/stix-${version}.jar-sources.jar

where ${version} is replaced with the version number in the Gradle build script.

Unit Testing

This project uses the Spock Framework for unit testing. These tests are authored in Groovy and exist under src/test/groovy path.

To execute the tests:

/gradlew -x signArchives test

Consider using -d/--debug or -i/--info for more details during test execution like so:

./gradlew -x signArchives -i

The test task will generated a report that can be found at build/reports/tests/index.html.

Examples

Examples exist in src/main/java/org/mitre/stix/examples

src/main/java/org/mitre/stix/examples/
├── CIQIdentity.java
├── CreationToolMetadata.java
├── IndicatorHash.java
├── XML2Object.java
└── XMLParser.java

To execute CIQIdentity on the command-line via Gradle, do the following:

./gradlew -PmainClass=org.mitre.stix.examples.CIQIdentity -x signArchives execute 

Addendum

The author sees this section out of scope, but added it in hopes it will help you over a hurdle.

Building On Windows

I don't frequently build on Windows so there is a chance the build may fail on this platform. You will need additional dependencies normally found in UNIX, such as, GNU patch. GNU Patch can be installed via either cygwin, Chocolatey, or directly. Then you'll need to work out permission elevation issues so Gradle can execute the command-line GNU patch command through Gradle's Ant integration. Alternatively, see the section on building using the Dockerfile.

To build on Windows use the gradlew batch script like so:

$ .\gradlew.bat -x signArchives

If the build goes well you will find the jars:

build\libs\stix-${version}.jar
build\libs\stix-${version}-javadoc.jar 
build\libs\stix-${version}.jar-sources.jar

where ${version} is replaced with the version number in the Gradle build script.

Building via the Dockerfile

If you have Docker installed, from the root of the project run the following to create a container image for this Dockerfile via:

docker build --rm -t stix/java-stix . 

Then create a container using the image you just created via:

docker run -it --rm --name java-stix stix/java-stix /bin/bash

To retreive the jar archives from the running docker container use following from the command-line of your docker host, not the container:

docker cp <container id>:/java-stix/build/libs/stix-1.2.0.2-SNAPSHOT-javadoc.jar .
docker cp <container id>:/java-stix/build/libs/stix-1.2.0.2-SNAPSHOT-sources.jar .
docker cp <container id>:/java-stix/build/libs/stix-1.2.0.2-SNAPSHOT.jar .

If the containder ID is not obvious, but you can also retrieve it via:

docker ps

An example of retrieving the snapshot jar would be the following:

docker cp 83ad9afb6096:/java-stix/build/libs/stix-1.2.0.2-SNAPSHOT.jar . 

By default the Docker container will build using OpenJdk 7.

Importing the project into Eclipse

As Eclipse's various Gradle plugins have varying degrees of usefulness, I usually import the project as a Java Project and not a Gradle Project.

You can still use Gradle EnIDE plugin to run the Gradle build script from the IDE, but you'll need to configure your Gradle Home to use via the Eclipse IDE preference panel.

After running the Gradle build script, if you are using the Eclipse IDE you may want to run the following from the command-line to set up the Ecipse environment:

./gradlew build cleanEclipse eclipse -x signArchives

It entirely depends on how smart yoour Eclipse Gradle plugin is and how you imported the project. The above command will change your prject to essentially a Java Project. If you run the command, then right-click on the Eclipse project and select "Refresh" to bring in the dependencies and source of JAXB Document Model. By default the generated source files are not editable to remmind you that changes to these files is usually a bad idea.

Opening the project into NetBeans

Like the eclipse section above, the author sees this section out of scope, but added it in hopes it will help you over the hurdle.

I've tested the project with NetBeans 8.0.1 and it works great with the Gradle JavaEE Support plugin. With the plugin installed, open the project and right-click on the project root and select build from the task panel.