stix2admiralty

This repository contains a small Python generator that builds STIX 2.1 marking-definition objects for the Admiralty source reliability and information credibility scales, then packages them into a STIX bundle.

The entrypoint is generate-objects.py.

What the script does

The script generates:

• 6 marking-definition objects for Admiralty information credibility (1-6)
• 6 marking-definition objects for Admiralty source reliability (A-F)
• 1 STIX bundle containing:
  • the DOGESEC identity object
  • the shared stix2extensions marking-definition object
  • the two extension-definition input objects
  • all generated marking-definition objects

The generated objects are deterministic:

• object IDs are created with UUIDv5
• the created timestamp is fixed
• bundle contents are sorted before hashing
• the bundle ID only changes when the bundled object content changes

This makes the output stable across repeated runs, which is useful for version control and downstream automation.

Requirements

• Python 3.9 or newer
• Network access to GitHub so the script can download the two required extension-definition JSON objects from muchdogesec/stix2extensions

The script only uses the Python standard library, so no package installation is required.

External inputs

The script pulls these upstream STIX objects directly from GitHub:

• DOGESEC identity: dogesec.json
• stix2extensions marking-definition: stix2extensions.json
• Admiralty information credibility extension-definition: marking_definition_admiralty_information_credibility.json
• Admiralty source reliability extension-definition: marking_definition_admiralty_source_reliability.json

Repository layout used for outputs

The script resolves output paths relative to the repository root and writes to this structure:

manually_generated/
  objects/
    marking-definition/
    bundle/

If the objects/marking-definition or objects/bundle directories do not exist, the script will create them.

How to run it

From the repository root:

PYTHONPATH=. python3 generate-objects.py

If GitHub is reachable, the script will download the extension-definition input objects and then write:

• individual marking-definition JSON files to manually_generated/objects/marking-definition/
• a bundle file to manually_generated/objects/bundle/bundle--<uuid>.json

Example output:

Wrote 12 marking-definition objects
Wrote bundle: /path/to/repo/manually_generated/objects/bundle/bundle--<uuid>.json
Bundle ID: bundle--...

How it works

1. Static metadata

The script defines fixed values for:

• a UUID namespace used to generate deterministic STIX IDs
• a fixed created timestamp: 2020-01-01T00:00:00.000Z
• STIX spec_version: 2.1
• the created_by_ref
• the two extension-definition IDs used in generated objects
• the raw GitHub URLs for the four upstream input objects

2. Admiralty code maps

Two in-memory dictionaries define the generated content:

• INFORMATION_CREDIBILITY
  • 1 = Confirmed by other sources
  • 2 = Probably true
  • 3 = Possibly true
  • 4 = Doubtful
  • 5 = Improbable
  • 6 = Truth cannot be judged
• SOURCE_RELIABILITY
  • A = Completely reliable
  • B = Usually reliable
  • C = Fairly reliable
  • D = Not usually reliable
  • E = Unreliable
  • F = Reliability cannot be judged

3. Deterministic STIX object generation

For each Admiralty code, the script builds a marking-definition object with:

• a deterministic STIX ID
• a human-readable name including the code and description
• an extensions block containing the Admiralty-specific code and description
• two fixed object_marking_refs

Information credibility and source reliability objects use different extension-definition IDs and different extension property names.

4. File naming

Each generated marking definition is written to a separate JSON file named after the STIX object ID:

• marking-definition--<uuid>.json

This keeps filenames stable and directly traceable to the object they contain.

5. Bundle creation

The script then creates a STIX bundle containing:

• the downloaded DOGESEC identity object
• the downloaded stix2extensions marking-definition object
• the downloaded information credibility extension-definition object
• the downloaded source reliability extension-definition object
• all generated marking-definition objects

Before assigning a bundle ID, it:

1. sorts all bundled objects by ID
2. serializes them into canonical JSON
3. hashes that JSON with SHA-256
4. uses the hash as input to a deterministic UUIDv5 bundle ID

This means the bundle ID is content-derived and reproducible.

Outputs

After a successful run, you should have:

manually_generated/objects/marking-definition/
  marking-definition--<uuid>.json
  marking-definition--<uuid>.json
  ...

manually_generated/objects/bundle/
  bundle--<uuid>.json

blog/representing_admiralty_codes_in_stix/

Support

Minimal support provided via the DOGESEC community.

License

Apache 2.0.

Useful supporting links

• Representing Admiralty Codes in STIX Without Giving Up Interoperability