{"id":22878905,"url":"https://github.com/oasis-open/cti-stix-visualization","last_synced_at":"2025-04-05T01:03:11.245Z","repository":{"id":11090185,"uuid":"68161626","full_name":"oasis-open/cti-stix-visualization","owner":"oasis-open","description":"OASIS TC Open Repository: Lightweight visualization for STIX 2.0 objects and relationships","archived":false,"fork":false,"pushed_at":"2024-12-03T20:28:02.000Z","size":1674,"stargazers_count":147,"open_issues_count":10,"forks_count":43,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-03-29T00:04:03.822Z","etag":null,"topics":["cti","cyber-threat-intelligence","javascript","json","oasis","stix","stix2","visualization","visualizer"],"latest_commit_sha":null,"homepage":"http://oasis-open.github.io/cti-stix-visualization","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oasis-open.png","metadata":{"files":{"readme":"README.Javascript.rst","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-09-14T01:22:30.000Z","updated_at":"2025-03-21T03:41:10.000Z","dependencies_parsed_at":"2024-12-13T16:43:26.654Z","dependency_job_id":"8d276822-47c4-4637-89cc-f6cc3994504c","html_url":"https://github.com/oasis-open/cti-stix-visualization","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oasis-open%2Fcti-stix-visualization","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oasis-open%2Fcti-stix-visualization/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oasis-open%2Fcti-stix-visualization/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oasis-open%2Fcti-stix-visualization/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oasis-open","download_url":"https://codeload.github.com/oasis-open/cti-stix-visualization/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247271514,"owners_count":20911587,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cti","cyber-threat-intelligence","javascript","json","oasis","stix","stix2","visualization","visualizer"],"created_at":"2024-12-13T16:35:32.612Z","updated_at":"2025-04-05T01:03:11.227Z","avatar_url":"https://github.com/oasis-open.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":".. contents::\n\n================\nJavascript Usage\n================\n\nThe STIX Visualizer is written in Javascript (the small bit of Python is for\nintegration into Jupyter).  This file documents the Javascript module.\n\nLibrary Design\n==============\n\nSTIX is a graph-like data model.  This library is designed to visualize STIX\ncontent in the natural way, as a graph.  It converts STIX content into a set of\nnodes and a set of edges.\n\nThe library separates the creation of graph data (as converted from STIX\ncontent) from how that data is visualized.  This allows for different\nviews of the same graph data.  If there is a lot of STIX content for example, a\nvisual graph rendering may be too cluttered or may not perform well.  The\nprimary rendering of the graph data is intended to be a graph.  But alternative\nviews may be more suitable under some circumstances.\n\nTwo view implementations are included.  There is a graph view based on\n`visjs \u003chttps://visjs.org/\u003e`_, and a simpler textual list view which just puts\ngraph data into a simple HTML list.\n\nJavascript API\n==============\n\nThe ``stix2viz`` module exports the following functions:\n\n- ``makeGraphData(stixContent, config)``\n- ``makeGraphView(domElement, nodeDataSet, edgeDataSet, stixIdToObject, config)``\n- ``makeListView(domElement, nodeDataSet, edgeDataSet, stixIdToObject, config)``\n\nThe configuration object which is the last parameter of all of these functions\nis documented in the `configuration \u003cConfiguration_\u003e`_ section.\n\nMaking Graph Data\n-----------------\n\nThe first step to visualizing STIX content using this library, is to create the\nbase graph data.  This is done with ``makeGraphData``.  It accepts STIX content\nin a few different forms, including a single STIX object, array of objects,\nor bundle of objects, as JSON text, plain Javascript object, array, or Map.\n\nThe function returns a 3-tuple,\n:code:`[nodeDataSet, edgeDataSet, stixIdToObject]`.  The first two elements are\n`DataSet \u003chttps://visjs.github.io/vis-data/data/dataset.html\u003e`_ objects with\nthe graph data; the last contains the same STIX content as was passed in, but\nin a normalized form, to simplify handling.  The normalized form is a Map\ninstance which maps STIX IDs to Map instances containing the data for each\nSTIX object.  All nested mappings are recursively converted to Map instances as\nnecessary.\n\nMaking a View\n-------------\n\nCreation of a view is done within the context of a web page.  One element from\nthe web page must be chosen to act as the root of the content which will\ncomprise the view.  The ``makeGraphView`` or ``makeListView`` function is\ncalled with this root element, all the values obtained from making the graph\ndata, and a configuration object.  The view should automatically appear in the\nweb page (depending on its styling).\n\nThese functions return instances of internal classes: the classes themselves\nare not exported, but the functions act as factories for them.  There are some\nutility methods defined on the classes, e.g. a ``destroy()`` method\nfor destroying the view and releasing resources.\n\nConfiguration\n=============\n\nAll three of the public API functions accept a configuration object.  Different\nlibrary components require different types of configuration, but it can all\nco-exist within the same object.  The components will look for and use whatever\nsettings they need.\n\nConfiguration can be given as JSON text, a plain Javascript object, or a Map.\nA few top-level keys map to various types of config settings, described in\nthe following subsections.\n\nPer STIX Type Settings\n----------------------\n\nSome settings are naturally organized per STIX type, e.g. how one labels graph\nnodes corresponding to particular STIX types.  One can use the STIX type as a\ntop-level configuration key, and map to type-specific settings:\n\n.. code:: JSON\n\n    {\n        \"\u003cstix_type\u003e\": {\n            \"displayProperty\": \"\u003cprop_name\u003e\",\n            \"displayIcon\": \"\u003cicon_file_name\u003e\",\n            \"embeddedRelationships\": [\"...relationships...\"]\n        }\n    }\n\nThe meanings are as follows:\n\n- ``displayProperty`` names a top-level property of STIX objects of the given\n  type.  The value of that property is used as the graph node label for nodes\n  corresponding to STIX objects of this type.  If an\n  `object-specific \u003cPer STIX Object Settings_\u003e`_ label is given, it will\n  override this setting.\n- ``displayIcon`` gives a URL to an icon file to use for this STIX type.  This\n  would be most relevant for graphical visualizations which use icons.  Both\n  library included views use this to create a legend: the legend will display\n  icons even though the list view is textual.\n- ``embeddedRelationships`` describes what embedded relationships should be\n  converted to graph edges, and how to create the edges.  The value of this\n  property is an array of length-three arrays::\n\n      [\"\u003cproperty_path\u003e\", \"\u003cedge_label\u003e\", true]\n\n  The first element is a `property path \u003cProperty Paths_\u003e`_ which should\n  identify a _ref(s) property in objects of that type.  The second is a label\n  to use for the edges, and the third element is a boolean which determines the\n  directionality of the resulting edges.  If ``true``, the edge direction will\n  be referrer -\u003e referent; otherwise, the direction will be the reverse.\n\n``displayProperty`` and ``embeddedRelationships`` are used only when creating\ngraph data.  ``displayIcon`` is used only in the views.\n\n\nPer STIX Object Settings\n------------------------\n\nThere is one config section which contains object-specific settings:\n``userLabels``.  It allows users to directly label individual STIX objects.\nIt is a mapping from STIX ID to label:\n\n.. code:: JSON\n\n    {\n        \"userLabels\": {\n            \"identity--349fbdc2-959e-4f76-9a44-256e226419ba\": \"Bob\"\n        }\n    }\n\nThis overrides per-type label settings.\n\nSTIX Object Filtering\n---------------------\n\nIt is possible to include or exclude STIX objects from being used to create\ngraph data, on the basis of some criteria:\n\n.. code:: JSON\n\n    {\n        \"include\": \"\u003ccriteria\u003e\",\n        \"exclude\": \"\u003ccriteria\u003e\"\n    }\n\n``include`` is used to describe which STIX objects to include; ``exclude``\nis used to describe which STIX objects to exclude.  Users can choose one of\nthese, depending on what is most natural for their usage.  It is also possible\nto include both settings.  If both are included, STIX objects are included\nwhich match ``include`` *and* do not match ``exclude``.\n\nHow to express the criteria is described in the next section.\n\nSTIX Object Match Criteria\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThese criteria are intended to support a true/false match capability on STIX\nobjects.  The design is based on Mongo queries, but is not the same.\n\nA set of criteria is expressed as a mapping.  Each entry in the mapping\nrepresents sub-criteria, and the sub-criteria represented by all map entries\nare implicitly AND'd.  At the top level, property path criteria and logical\noperators are most useful.  At nested levels, one can use value and presence\ncriteria as well.\n\nValue Criteria\n^^^^^^^^^^^^^^\n\nValue criteria express a comparison directly on some value.  With respect to\nSTIX objects, this type of criteria is not useful at the top level because\nuseful checks against whole objects (and arrays) are not defined.  They are\nonly useful at nested levels, applied to simple values.  Value criteria can be\ngiven as a plain value, which acts as an equality check, or a mapping with an\noperator which maps to an operand value.\n\nFor example:\n\n.. code:: JSON\n\n    { \"$gt\": 80 }\n\nAn example of usage of the above value criterion is:\n\n.. code:: JSON\n\n    {\n        \"confidence\": { \"$gt\": 80 }\n    }\n\nThis matches objects with a confidence value greater than 80.  One could use\n``$eq`` to perform an equality check, or use 80 directly as the value\ncriterion, which means the same thing.\n\nSupported value criterion operators include: ``$eq``, ``$gt``, ``$gte``,\n``$in``, ``$lt``, ``$lte``, ``$ne``, ``$nin``.  ``$in`` and ``$nin`` must map\nto arrays, since they mean \"in\" and \"not in\" the given array.\n\nProperty Path Criteria\n^^^^^^^^^^^^^^^^^^^^^^\n\nA property path criterion maps a property path to some sub-criteria.  The\nproperty path acts as a kind of \"selector\" of values from the object (or some\nsub-object).  These values are checked against the sub-criteria, and the\nresults are OR'd.\n\nFor example, given object:\n\n.. code:: JSON\n\n    {\n        \"foo\": [\n            {\"bar\": 1},\n            {\"bar\": 2}\n        ]\n    }\n\nCriteria:\n\n.. code:: JSON\n\n    {\n        \"foo.bar\": 1\n    }\n\nwill produce a match.  The \"foo.bar\" property path selects values 1 and 2, and\n1 as the mapped criterion is a value sub-criterion which acts as a direct\nequality check with that value (using the Javascript \"===\" operator).  These\nchecks are implicitly OR'd, so the net result is equivalent to\n(1 === 1 || 2 === 1).\n\nLogical Operator Criteria\n^^^^^^^^^^^^^^^^^^^^^^^^^\n\nLogical operator criteria are map entries with keys ``$and``, ``$or``, or\n``$not``.  They behave as one would expect: the first two must map to arrays\nof criteria; the last maps to a single criterion.\n\n``$not`` deserves some special discussion.  It causes evaluation of the mapped\ncriterion, and simply inverts the result.  It does *not* invert any nested\noperators, so it can result in subtle behavioral differences as compared to\nan inverted operator.  For example, given object:\n\n.. code:: JSON\n\n    {\n        \"foo\": [1, 2]\n    }\n\nThe following criteria produce results as shown:\n\n- :code:`{\"foo\": {\"$in\": [2, 3]}}`: match\n- :code:`{\"foo\": {\"$nin\": [2, 3]}}`: match\n- :code:`{\"foo\": {\"$not\": {\"$in\": [2, 3]}}}`: no match\n\nThe first is equivalent to (1 in [2, 3]) OR (2 in [2, 3]), which is true; the\nsecond is equivalent to (1 not in [2, 3]) OR (2 not in [2, 3]) which is also\ntrue; and the last is the inversion of the first, so it is false.\n\nThe second is checking for a value not in [2, 3], whereas the last is\neffectively ensuring that *none* of the values are in [2, 3], and those are\ndifferent criteria.\n\nPresence Criteria\n^^^^^^^^^^^^^^^^^\n\nThere is one presence criterion, which occurs when a map key is ``$exists``.\nIt only makes sense nested directly under a property path criterion, and is\nintended to act as a property presence check.  It can't be quite that simple\nthough, because a property *path* isn't as simple as a plain property name.\nSo this criterion has a more general behavior, but acts as expected when the\nproperty path has only one component (is just a property name).\n\nThe ``$exists`` key must map to a boolean.  If it maps to true, the criterion\nmatches if the property path selects any values from the object.  If it maps\nto false, the criterion matches if the property path selects nothing from the\nobject.\n\nFor example, given object:\n\n.. code:: JSON\n\n    {\n        \"foo\": [\n            {\"bar\": 1},\n            {\"bar\": 2}\n        ]\n    }\n\nThe following criteria produce results as shown:\n\n- :code:`{\"foo\": {\"$exists\": true}}`: match\n- :code:`{\"bar\": {\"$exists\": false}}`: match\n- :code:`{\"foo.bar\": {\"$exists\": false}}`: no match\n\nProperty Paths\n--------------\n\nProperty paths are used in various places in the configuration settings to\nidentify parts of STIX objects.  They can also be seen as \"selectors\" of\nsub-components of a given object.  If array-valued properties are present, a\nsingle property path may identify multiple parts of the same object.  Property\npaths are designed to be transparent to arrays.  There is no way to identify a\nparticular element of an array in a property path.\n\nProperty paths are strings in a particular syntax.  That syntax is a sequence\nof property names separated by dots.  Property paths shouldn't begin or end\nwith a dot, there should be no adjacent dots, and the path should not be empty.\nProperty names can't contain dots; there is no escaping.  But this should be\nokay since STIX property names should not contain dots.\n\nFor example, given structure:\n\n.. code:: JSON\n\n    {\n        \"a\": [\n            {\"b\": 1},\n            {\n                \"b\": {\n                    \"c\": [2, 3]\n                }\n            }\n        ]\n    }\n\nPaths and selected sub-components include:\n\n- \"a\" -\u003e {\"b\": 1}, {\"b\": {\"c\": [2, 3]}}  (two results)\n- \"a.b\" -\u003e 1, {\"c\": [2, 3]} (two results)\n- \"a.b.c\" -\u003e 2, 3 (two results)\n- \"a.b.c.d\" -\u003e (no results)\n\nNotice that if the property path refers to an array (i.e. the last path\ncomponent names an array-valued property), it does not select the array itself,\nit selects the individual elements of the array.  If those individual elements\nare themselves arrays, they are presently *not* searched.  I.e. if the path\nrefers to an array, the resulting selection is not as if the array was\nflattened.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foasis-open%2Fcti-stix-visualization","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foasis-open%2Fcti-stix-visualization","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foasis-open%2Fcti-stix-visualization/lists"}