From 1d5428afa7c4442762737fdca8bad3d533f5e275 Mon Sep 17 00:00:00 2001 From: Gordon Chung Date: Mon, 6 Jan 2014 14:52:17 -0500 Subject: pycadf documentation add basic documentation on CADF spec. Closes-Bug: #1279951 Change-Id: Ie1703d9b5109d8275377857e5362e3b09385f647 Implements: blueprint document-pycadf --- doc/Makefile | 182 ++++++++++++++++++++ doc/source/_templates/.placeholder | 0 doc/source/api/index.rst | 8 + doc/source/conf.py | 261 +++++++++++++++++++++++++++++ doc/source/event_concept.rst | 175 +++++++++++++++++++ doc/source/images/audit_event.png | Bin 0 -> 36633 bytes doc/source/images/middleware.png | Bin 0 -> 48742 bytes doc/source/images/monitor_event.png | Bin 0 -> 100632 bytes doc/source/images/observer_cadf.png | Bin 0 -> 32298 bytes doc/source/index.rst | 61 +++++++ doc/source/middleware.rst | 103 ++++++++++++ doc/source/specification/attachments.rst | 58 +++++++ doc/source/specification/credentials.rst | 56 +++++++ doc/source/specification/endpoints.rst | 53 ++++++ doc/source/specification/events.rst | 96 +++++++++++ doc/source/specification/geolocations.rst | 88 ++++++++++ doc/source/specification/hosts.rst | 54 ++++++ doc/source/specification/identifiers.rst | 33 ++++ doc/source/specification/index.rst | 28 ++++ doc/source/specification/measurements.rst | 77 +++++++++ doc/source/specification/paths.rst | 25 +++ doc/source/specification/reasons.rst | 49 ++++++ doc/source/specification/reportersteps.rst | 60 +++++++ doc/source/specification/resources.rst | 64 +++++++ doc/source/specification/tags.rst | 29 ++++ doc/source/specification/taxonomy.rst | 33 ++++ doc/source/specification/timestamps.rst | 34 ++++ 27 files changed, 1627 insertions(+) create mode 100644 doc/Makefile create mode 100644 doc/source/_templates/.placeholder create mode 100644 doc/source/api/index.rst create mode 100644 doc/source/conf.py create mode 100644 doc/source/event_concept.rst create mode 100644 doc/source/images/audit_event.png create mode 100644 doc/source/images/middleware.png create mode 100644 doc/source/images/monitor_event.png create mode 100644 doc/source/images/observer_cadf.png create mode 100644 doc/source/index.rst create mode 100644 doc/source/middleware.rst create mode 100644 doc/source/specification/attachments.rst create mode 100644 doc/source/specification/credentials.rst create mode 100644 doc/source/specification/endpoints.rst create mode 100644 doc/source/specification/events.rst create mode 100644 doc/source/specification/geolocations.rst create mode 100644 doc/source/specification/hosts.rst create mode 100644 doc/source/specification/identifiers.rst create mode 100644 doc/source/specification/index.rst create mode 100644 doc/source/specification/measurements.rst create mode 100644 doc/source/specification/paths.rst create mode 100644 doc/source/specification/reasons.rst create mode 100644 doc/source/specification/reportersteps.rst create mode 100644 doc/source/specification/resources.rst create mode 100644 doc/source/specification/tags.rst create mode 100644 doc/source/specification/taxonomy.rst create mode 100644 doc/source/specification/timestamps.rst (limited to 'doc') diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..5213d9a --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,182 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " wadl to build a WADL file for api.openstack.org" + +clean: + rm -rf $(BUILDDIR)/* + +html: check-dependencies + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +.PHONY: check-dependencies +check-dependencies: + @python -c 'import sphinxcontrib.autohttp.flask' >/dev/null 2>&1 || (echo "ERROR: Missing Sphinx dependencies. Run: pip install sphinxcontrib-httpdomain" && exit 1) + +wadl: + $(SPHINXBUILD) -b docbook $(ALLSPHINXOPTS) $(BUILDDIR)/wadl + @echo + @echo "Build finished. The WADL pages are in $(BUILDDIR)/wadl." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/pyCADF.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/pyCADF.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/pyCADF" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/pyCADF" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/doc/source/_templates/.placeholder b/doc/source/_templates/.placeholder new file mode 100644 index 0000000..e69de29 diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst new file mode 100644 index 0000000..3da71d0 --- /dev/null +++ b/doc/source/api/index.rst @@ -0,0 +1,8 @@ +============== + API Reference +============== + +.. toctree:: + :maxdepth: 1 + + autoindex diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..1dc84b4 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,261 @@ +# -*- coding: utf-8 -*- +# +# pyCADF documentation build configuration file, created by +# sphinx-quickstart on Sun Mar 16 22:32:24 2014. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# This is required for ReadTheDocs.org, but isn't a bad idea anyway. +os.environ['DJANGO_SETTINGS_MODULE'] = 'openstack_dashboard.settings' + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx.ext.coverage', + 'sphinx.ext.pngmath', + 'sphinx.ext.viewcode', + 'oslosphinx' +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'pyCADF' +copyright = u'2014, gordon chung' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '1.0' +# The full version, including alpha/beta/rc tags. +release = '1.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +#html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +html_theme_options = { + "nosidebar": "false" +} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'pyCADFdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'pyCADF.tex', u'pyCADF Documentation', + u'gordon chung', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'pycadf', u'pyCADF Documentation', + [u'gordon chung'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'pyCADF', u'pyCADF Documentation', + u'gordon chung', 'pyCADF', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False diff --git a/doc/source/event_concept.rst b/doc/source/event_concept.rst new file mode 100644 index 0000000..913f174 --- /dev/null +++ b/doc/source/event_concept.rst @@ -0,0 +1,175 @@ +.. + Copyright 2014 IBM Corp. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. _event_concept: + +======= + Events +======= + +The principal goal of this specification is to ensure that similar auditable +events, such as a "logon" or "critical resource update" resolve to the same +data format with prescriptive data types, entities, and properties to +facilitate reporting, query, federation, and aggregation. + +Defining Events +=============== + +The event model is intended to describe the interactions between resources +that compose a cloud service. Conceptually, the event is based upon the +perspective of a single RESOURCE called the OBSERVER that is responsible for +observing the Actual Event and creating the (initial) CADF Event Record. + +.. figure:: ./images/observer_cadf.png + :figwidth: 100% + :align: center + :alt: Figure 1: Observer perspective of an Event + +At a minimum, an Event must include the following attributes to be +CADF-compliant: eventType, observer, initiator, target, action, and outcome. +CADF's event model is extensible so any additional attributes that may better +help describe the event can be added to the event model as an additional +attribute. + +.. note:: + + In some cases, the OBSERVER, INITIATOR, and TARGET could reference the same + resource. The precise interpretation of these components, therefore, will + depend somewhat on the type of event being recorded, and the specific + activity and resources involved. + +Use Case Examples +================= + +1. Auditing access to a controlled resource + +Scenario: A cloud provider has a software component that manages identity and +access control that we will call an "identity management service". This +service is required, by the provider's security policy, to log all user +activities including "logon" attempts against any servers within the +provider's infrastructure. + +.. figure:: ./images/audit_event.png + :figwidth: 100% + :align: center + :alt: Figure 2: Conceptually mapping values of an audit event + +================= ========================== ========================================================================================== +Event Attribute Value Reason +================= ========================== ========================================================================================== +eventType activity OBSERVER is required to report any user security activity +observer.typeURI service/security/identity Value from the CADF Resource Taxonomy most closely describes an "Identity Manager Service" +initiator.typeURI data/security/account/user Value from the CADF Resource Taxonomy most closely describes a "user" +action authenticate/logon Value from the CADF Action Taxonomy most closely describes a user "logon" action. +target.typeURI service/compute/node Value from the CADF Resource Taxonomy most closely describes a target "server" +outcome success Any valid CADF Outcome Taxonomy value that describes result of action +measurement N/A A MEASUREMENT component is not required for "activity" type events. +REASON N/A A REASON component is not required for "activity" type events. +================= ========================== ========================================================================================== + +Event serialisation (including some optional attributes for additional +details):: + + { + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + "eventTime": "2014-02-27T19:29:30.855665+0000", + "target": { + "typeURI": "service/compute/node", + # optional Endpoints to describe compute node + "addresses": [{"url": "http://9.26.26.250:8774/v2/e7e2bcc9c0df4f3eabcd412ae62503f6", "name": "admin"}, + {"url": "http://9.26.26.250:8774/v2/e7e2bcc9c0df4f3eabcd412ae62503f6", "name": "private"}, + {"url": "http://9.26.26.250:8774/v2/e7e2bcc9c0df4f3eabcd412ae62503f6", "name": "public"}], + "id": "openstack:06747855d62547d4bfd707f75b8a1c54", + "name": "nova"}, + "observer": {"id": "target"}, # shortform to show Observer Resource is the same as Target + # tags use to query events on + "tags": ["correlation_id?value=openstack:56cdde6f-6b4e-48a4-94e6-defb40522fb2"], + "eventType": "activity", + "initiator": { + "typeURI": "data/security/account/user", + "name": "admin", + # optional Credential to describe resource + "credential": {"token": "MIIQzgYJKoZIhvcNAQcCoIIQvzCCELsC xxxxxxxx zqvD9OPWZm7VQpYNK2EvrZi-mTvb5A==", + "identity_status": "Confirmed"}, + # optional Host to describe resource + "host": {"agent": "python-novaclient", "address": "9.26.26.250"}, + "project_id": "openstack:e7e2bcc9c0df4f3eabcd412ae62503f6", + "id": "openstack:68a3f50705a54f799ce94380fc02ed8a"}, + # optional Reason for activity event + "reason": {"reasonCode": "200", "reasonType": "HTTP"}, + # list of Resources which edited event + "reporterchain": [{"reporterTime": "2014-02-27T19:29:31.043902+0000", + "role": "modifier", + "reporter": {"id": "target"}}], + "action": "authenticate/logon", + "outcome": "success", + "id": "openstack:0a196053-95de-48f8-9890-4527b25b5007", + # Event model is extensible so additional attributes may be added to describe model + "requestPath": "/v2/e7e2bcc9c0df4f3eabcd412ae62503f6/os-certificates"} + +2. Periodic monitoring resource status + +Scenario: A cloud provider has software monitoring agents(Ceilometer) +installed on every server(Nova) that it makes available as an IaaS resource +to its customers. These agents are required to provide periodic informational +status of each server's CPU utilisation along with metric data to their +operations management software by using the CADF Event Record format. + +.. figure:: ./images/monitor_event.png + :figwidth: 100% + :align: center + :alt: Figure 3: Conceptually mapping values of an monitor event + +================= ====================== ========================================================================================== +Event Attribute Value Reason +================= ====================== ========================================================================================== +eventType monitor OBSERVER is required to monitor a server's CPU utilization +observer.typeURI service/oss/monitoring Value from the CADF Resource Taxonomy most closely describes a "software monitoring agent" +initiator.typeURI service/oss/monitoring OBSERVER is also the INITIATOR of this monitoring event +action monitor Value from the CADF Action Taxonomy +target.typeURI service/compute/cpu Value from the CADF Resource Taxonomy most closely describes a server’s "cpu" +outcome success OBSERVER successfully obtained and reported a CPU utilization measurement +measurement 80% MEASUREMENT component is required and the observed value is 80% CPU utilisation +reason N/A REASON component is not required for "monitor" type events. +================= ====================== ========================================================================================== + +Event serialisation:: + + { + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + "eventTime": "2014-02-27T19:29:30.855665+0000", + "target": { + "typeURI": "service/compute/cpu", + "id": "openstack:06747855d62547d4bfd707f75b8a1c54", + "name": "instance"}, + "observer": {"id": "initiator"}, + "eventType": "monitor", + "initiator": { + "typeURI": "service/oss/monitoring", + "name": "ceilometer-pollster", + "id": "openstack:68a3f50705a54f799ce94380fc02ed8a"}, + "measurement": [{ + "result": "80", + "metric": {"metricId": "openstack:", + "unit": "%", + "name": "CPU utilisation metric"} + }] + "action": "monitor", + "outcome": "success", + "id": "openstack:0a196053-95de-48f8-9890-4527b25b5007"} + +.. note:: + + Additional use cases can be found in the Full CADF specification. \ No newline at end of file diff --git a/doc/source/images/audit_event.png b/doc/source/images/audit_event.png new file mode 100644 index 0000000..57c99ca Binary files /dev/null and b/doc/source/images/audit_event.png differ diff --git a/doc/source/images/middleware.png b/doc/source/images/middleware.png new file mode 100644 index 0000000..5c2b130 Binary files /dev/null and b/doc/source/images/middleware.png differ diff --git a/doc/source/images/monitor_event.png b/doc/source/images/monitor_event.png new file mode 100644 index 0000000..8853d31 Binary files /dev/null and b/doc/source/images/monitor_event.png differ diff --git a/doc/source/images/observer_cadf.png b/doc/source/images/observer_cadf.png new file mode 100644 index 0000000..f79a8cf Binary files /dev/null and b/doc/source/images/observer_cadf.png differ diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..a72e1a9 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,61 @@ +.. + Copyright 2014 IBM Corp. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +=============================== + PyCADF developer documentation +=============================== + +The `CADF (Cloud Audit Data Federation Working Group)`_ is working to develop +open standards for audit data which can be federated from cloud providers, +with the intent to elevate customer’s trust in cloud hosted applications. + +Specifications and profiles produced by the CADF will help protect the +investments of companies seeking to move their applications to cloud +deployment models and preserve their ability to audit operational processes, +regardless of their chosen cloud provider. The CADF develops specifications +for audit event data and interface models and a compatible interaction model +that will describe interactions between IT resources for cloud deployment models. + +pyCADF is the python implementation of the CADF specification + +This documentation offers information on how CADF works and how to +contribute to the project. + +.. _CADF (Cloud Audit Data Federation Working Group): http://www.dmtf.org/standards/cadf + +Table of contents +================= + +.. toctree:: + :maxdepth: 2 + + api/index + specification/index + event_concept + middleware + +.. update index + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + +To Do +===== + +.. todolist:: diff --git a/doc/source/middleware.rst b/doc/source/middleware.rst new file mode 100644 index 0000000..920279a --- /dev/null +++ b/doc/source/middleware.rst @@ -0,0 +1,103 @@ +.. + Copyright 2014 IBM Corp + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. _middleware: + +================= + Audit middleware +================= + +The pyCADF library provides an optional WSGI middleware filter which allows +the ability to audit api requests for each component of OpenStack. + +The audit middleware filter utilises environment variables to build the CADF +event. + +.. figure:: ./images/middleware.png + :figwidth: 100% + :align: center + :alt: Figure 1: Audit middleware in Nova pipeline + +The figure above shows the middleware in Nova's pipeline. + +Enabling audit middleware +========================= +To enable the audit middleware, the following requirements need to be +satisfied: + +1. pyCADF library must be added to the requirements file of the project to be + audited. + +2. The project should utilise oslo.messaging_ notification system. + +.. note:: + + If the project utilises oslo's `old notification system`_, a compatible + middleware can be synced from oslo-incubator's `middleware code base`_. + +If the above requirements are satisfied, auditing can be enabled by editing +the project's api-paste.ini file to include the following filter definition: + +:: + + [filter:audit] + paste.filter_factory = pycadf.middleware.audit:AuditMiddleware.factory + +or + +:: + + [filter:audit] + paste.filter_factory = .openstack.common.middleware.audit:AuditMiddleware.factory + +The filter should be included after Keystone's auth_token middleware so it can +utilise environment variables set by Keystone's middleware. Below is an +example using Nova's WSGI pipeline:: + + [composite:openstack_compute_api_v2] + use = call:nova.api.auth:pipeline_factory + noauth = faultwrap sizelimit noauth ratelimit osapi_compute_app_v2 + keystone = faultwrap sizelimit authtoken keystonecontext ratelimit audit osapi_compute_app_v2 + keystone_nolimit = faultwrap sizelimit authtoken keystonecontext audit osapi_compute_app_v2 + +.. _oslo.messaging: http://www.dmtf.org/standards/cadf +.. _old notification system: https://github.com/openstack/oslo-incubator +.. _middleware code base: https://github.com/openstack/oslo-incubator/tree/master/openstack/common/middleware + +Configure audit middleware +========================== +To properly audit api requests, the audit middleware requires an +api_audit_map.conf to be defined. The project's corresponding +api_audit_map.conf file is included in the `pyCADF library`_. + +By default, the audit middleware filter expects the map file to be located in +the same folder as the other conf files related to the project +(ie.'/etc/' folder). This default functionality is to be deprecated +and so the location should be specified explicitly by adding the path to the +'audit_map_file' option of the filter definition:: + + [filter:audit] + paste.filter_factory = pycadf.middleware.audit:AuditMiddleware.factory + audit_map_file = /etc/nova/api_audit_map.conf + +Additional options can be set:: + + [filter:audit] + paste.filter_factory = pycadf.middleware.audit:AuditMiddleware.factory + audit_map_file = /etc/nova/api_audit_map.conf + service_name = test # opt to set HTTP_X_SERVICE_NAME environ variable + ignore_req_list = GET,POST # opt to ignore specific requests + +.. _pyCADF library: https://github.com/openstack/pycadf/tree/master/etc/pycadf diff --git a/doc/source/specification/attachments.rst b/doc/source/specification/attachments.rst new file mode 100644 index 0000000..beba392 --- /dev/null +++ b/doc/source/specification/attachments.rst @@ -0,0 +1,58 @@ +.. + Copyright 2014 IBM Corp. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. _attachments: + +============ + Attachments +============ + +An attachment is a container for data or "content" that may follow any +structure – from an atomic type to a complex hierarchy. However, it is +desirable for processing and interoperability that the type – or +structure – of the content be identified by a simple value. To this end the +attachment also contains a "content type", i.e., a URI that identifies the +kind of content. + +Attachments are intended to be used for inclusion of domain-specific, +informative, or descriptive information. + +=========== ========= ======== ====================================================================================== +Property Type Required Description +=========== ========= ======== ====================================================================================== +typeURI xs:anyURI Yes The URI that identifies the type of data contained in the "content" property. +content xs:any Yes A container that contains any type of data (as defined by the "contentType" property). +contentType xs:string Yes An optional name that can be used to provide an identifying name for the content. +=========== ========= ======== ====================================================================================== + +Serialisation +============= + +json:: + + { + ..., + "attachments": [ + { + "content": "xs:any", + "contentType": "xs:anyURI" + }, + { + "content": "xs:any", + "contentType": "xs:anyURI" + } + ] + } + diff --git a/doc/source/specification/credentials.rst b/doc/source/specification/credentials.rst new file mode 100644 index 0000000..0132150 --- /dev/null +++ b/doc/source/specification/credentials.rst @@ -0,0 +1,56 @@ +.. + Copyright 2014 IBM Corp. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. _credentials: + +============ + Credentials +============ + +This type provides a means to describe various credentials along with any +information about the authority that is responsible for maintaining them. +This is intended to be associated with a CADF Resource’s identity and reflects +any authorizations or identity assertions the resource may use to gain access +to other resources. + +========== ========= ======== =================================================================================================== +Property Type Required Description +========== ========= ======== =================================================================================================== +type xs:anyURI No Type of credential. (e.g., auth. token, identity token, etc.) +token xs:any Yes The primary opaque or non-opaque identity or security token (e.g., an opaque or obfuscated user ID) +authority xs:anyURI No The trusted authority (a service) that understands and can verify the credential. +assertions cadf:Map No Optional list of additional assertions or attributes that belong to the credential +========== ========= ======== =================================================================================================== + +Serialisation +============= + +json:: + + { + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + "action": "authenticate", + ..., + "initiator": { + "id": "joe.user@tenant1.com", + "typeURI": "data/security/account/user", + ..., + "credential": { + "type": "https://mycloud.com/v2/token", + "token": "myuuid:1ef0-abdf-xxxx-xxxx" + } + } + } + diff --git a/doc/source/specification/endpoints.rst b/doc/source/specification/endpoints.rst new file mode 100644 index 0000000..b64b4b6 --- /dev/null +++ b/doc/source/specification/endpoints.rst @@ -0,0 +1,53 @@ +.. + Copyright 2014 IBM Corp. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. _endpoints: + +========== + Endpoints +========== + +The Endpoint type is used to provide information about a resource's location +on a network. + +======== ========= ======== ================================================================================= +Property Type Required Description +======== ========= ======== ================================================================================= +url xs:anyURI Yes The network address of the endpoint; for IP-based addresses +name xs:string No An optional property to provide a logical name for the endpoint +port xs:string No An optional property to provide the port value separate from the address property +======== ========= ======== ================================================================================= + +Serialisation +============= + +json:: + + { + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + ..., + "target": { + "id": "myscheme://mydomain/resource/id/0001", + "name": "server_0001", + "addresses": [{ + "name": "public", + "url": "http://mydomain/mypath/server-0001/" + }, + ... + ], + ... + } + } + diff --git a/doc/source/specification/events.rst b/doc/source/specification/events.rst new file mode 100644 index 0000000..9bcc311 --- /dev/null +++ b/doc/source/specification/events.rst @@ -0,0 +1,96 @@ +.. + Copyright 2014 IBM Corp. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. _events: + +======= + Events +======= + +The CADF Event Model applies semantics to the activities, resources, +information, and changes within a cloud provider’s infrastructure and models +these using the concept of an event. + +============= =================== ========= ============================================================================================================================================================= +Property Type Required Description +============= =================== ========= ============================================================================================================================================================= +id cadf:Identifier Yes The unique identifier of the CADF Event Record +typeURI cadf:Path Dependent Can be used to declare versioning of Events. +eventType xs:string Yes The classification of the type of event +eventTime cadf:Timestamp Yes The OBSERVER's best estimate as to the time the Actual Event occurred or began +action cadf:Path Yes This property represents the event's ACTION +outcome cadf:Path Yes A valid classification value from the CADF Outcome Taxonomy +initiator cadf:Resource Dependent The event's INITIATOR. Required if not initiatorId +initiatorId cadf:Identifier Dependent The event's INITIATOR resource by reference. Required if not initiator +target cadf:Resource Dependent The event's TARGET. Required if not targetId +targetId cadf:Identifier Dependent The event's TARGET by reference. Required if not target +observer cadf:Resource Dependent The event's OBSERVER. Required if not observerId +observerId cadf:Identifier Dependent The event's OBSERVER by reference. Required if not observer +reason cadf:Reason No Domain-specific reason code and policy data that provides an additional level of detail to the outcome value. Required if the eventType property is "control" +severity xs:string No Describes domain-relative severity assigned to the event by the OBSERVER. This property's value is non-normative +measurements cadf:Measurement[] Dependent Any measurement (values) associated with the event. Required if the eventType property is "monitor" +name xs:string No A descriptive name for the event +tags cadf:Tag[] No Array of Tags that MAY be used to further qualify or categorize the CADF Event Record +attachments cadf:Attachment[] No Array of extended or domain-specific information about the event or its context +reporterchain cadf:Reporterstep[] No Array of Reporterstep typed data that contains information about the sequenced handling of or change to the associated CADF Event Record by any REPORTER +============= =================== ========= ============================================================================================================================================================= + +Serialisation +============= + +json:: + + { + 'typeURI': 'http://schemas.dmtf.org/cloud/audit/1.0/event', + 'id': 'openstack:a80dc5ee-be83-48ad-ad5e-6577f2217637‘, + 'eventType': 'activity', + 'action': 'read', + 'outcome': 'success', + 'reason': {'reasonCode': '200', 'reasonType': 'HTTP'}, + 'eventTime': '2014-01-17T23:23:38.109989+0000', + 'initiator': { + 'id': 'openstack:95f12d248a234a969f456cd2c794f29a' + 'typeURI': 'service/security/account/user', + 'name': ‘admin', + 'project_id': 'openstack:e55b158759854ea6a7852aa76632c6c1', + 'credential': { + 'token': ‘MIIQBgYJKoZIhvcNAQcCoIIP9z xxxxxx KoZIhvcIP9z=‘, + 'identity_status': 'Confirmed'}, + 'host': { + 'agent': 'python-novaclient', + 'address': '9.26.27.109'}, + }, + 'target': { + 'id': 'openstack:0f126160203748a5b4923f2eb6e3b7db', + 'typeURI': ‘service/compute/servers', + 'name': 'nova‘ + 'addresses': [ + {'url': 'http://9.26.27.109:8774/v2/e55b158759854ea6a7852aa76632c6c1', + 'name': 'admin'}, + {'url': 'http://9.26.27.109:8774/v2/e55b158759854ea6a7852aa76632c6c1', + 'name': 'private'}, + {'url': 'http://9.26.27.109:8774/v2/e55b158759854ea6a7852aa76632c6c1', + 'name': 'public'} + ], + }, + 'observer': { 'id': 'target'}, + 'reporterchain': [ + {'reporterTime': '2014-01-17T23:23:38.154152+0000', + 'role': 'modifier', + 'reporter': {'id': 'target'}} + ], + 'requestPath': '/v2/56600971-90f3-4370-807f-ab79339381a9/servers', + 'tags': ['correlation_id?value=openstack:bcac04dc-e0be-4110-862c-347088a7836a'] + } diff --git a/doc/source/specification/geolocations.rst b/doc/source/specification/geolocations.rst new file mode 100644 index 0000000..43211b3 --- /dev/null +++ b/doc/source/specification/geolocations.rst @@ -0,0 +1,88 @@ +.. + Copyright 2014 IBM Corp. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. _geolocations: + +============= + Geolocations +============= + +Geolocation information, which reveals a resource’s physical location, is +obtained by using tracking technologies such as global positioning system +(GPS) devices, or IP geolocation by using databases that map IP addresses to +geographic locations. Geolocation information is widely used in +context-sensitive content delivery, enforcing location-based access +restrictions on services, and fraud detection and prevention. + +Due to the intense concerns about security and privacy, countries and regions +introduced various legislation and regulation. To determine whether an event +is compliant sometimes depends on the geolocation of the event. Therefore, it +is crucial to report geolocation information unambiguously in an audit trail. + +=========== ========= ======== =============================================================================================================== +Property Type Required Description +=========== ========= ======== =============================================================================================================== +id xs:anyURI No Optional identifier for a geolocation +latitude xs:string No The latitude of a geolocation +longitude xs:string No The longitude of a geolocation +elevation xs:double No The elevation of a geolocation in meters +accuracy xs:double No The accuracy of a geolocation in meters +city xs:string No The city of a geolocation +state xs:string No The state/province of a geolocation +regionICANN xs:string No A region (e.g., a country, a sovereign state, a dependent territory or a special area of geographical interest) +annotations cadf:Map No User-defined geolocation information (e.g., building name, room number) +=========== ========= ======== =============================================================================================================== + +Usage Requirements +================== +1. Geolocation typed data SHALL contain at least one valid property and + associated value. + +2. Geolocation typed data SHALL NOT be used to represent virtual or logical + locations (e.g. network zone). + +3. For each geolocation data instance, the properties SHALL be consistent. + That is, all properties SHALL consistently represent the same geographic + location and SHALL NOT provide conflicting value data. + +:: + + Example: ‘latitude’, ‘longitude’ and ‘region’ are all supplied as + properties describing the same geolocation, the 'latitude' and + 'longitude' properties' coordinate values should resolve to the + same geographic location as described by the 'region' + property's value. + +4. ICANN's implementation plan states "Upper and lower case characters are + considered to be syntactically and semantically identical"; therefore, + the "regionICANN" property's values MAY be either upper or lower case. + +Serialisation +============= + +json:: + + { + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + ..., + "target": { + ..., + "geolocation": { + "latitude": "+372207.90", + "longitude": "-1220210.20", + "elevation": "10" + } + } + } diff --git a/doc/source/specification/hosts.rst b/doc/source/specification/hosts.rst new file mode 100644 index 0000000..f77c130 --- /dev/null +++ b/doc/source/specification/hosts.rst @@ -0,0 +1,54 @@ +.. + Copyright 2014 IBM Corp. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. _hosts: + +====== + Hosts +====== + +Most resources that are referenced in an IT or cloud infrastructure are +conceptually "hosted on" or "hosted by" other resources. For example, +"applications" are hosted on "web servers" or "users" may be hosted on a +"network connected device" or a "terminal". In addition, networked resources +are "hosted" by some device attached to some network. + +The host resource often provides context or location information for the +resource it is hosting at the time the Actual Event was observed and recorded +(e.g., an IP address, software agent, platform, etc.). Providing a means to +record host information with a CADF Event Record is valuable for audit purposes +because compliance policies and rules are often based on such information. + +======== =============== ======== ============================================== +Property Type Required Description +======== =============== ======== ============================================== +id cadf:Identifier No The optional identifier of the host RESOURCE +address xs:anyURI No The optional address of the host RESOURCE +agent xs:string No The optional agent (name) of the host RESOURCE +platform xs:string No The optional platform of the host RESOURCE +======== =============== ======== ============================================== + +Serialisation +============= + +json:: + + { + "id": "myuuid:1234-5678-90abc-defg-0000", + "address": "10.0.2.15", + "agent": "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:18.0)", + "platform": "Linux version 3.5.0-23-generic (gcc version 4.6.3 (Ubuntu/Linaro 4.6.3-1ubuntu5) ) #35~precise1-Ubuntu SMP Fri Jan 25 17:15:33 UTC 2013" + } + diff --git a/doc/source/specification/identifiers.rst b/doc/source/specification/identifiers.rst new file mode 100644 index 0000000..55bc65d --- /dev/null +++ b/doc/source/specification/identifiers.rst @@ -0,0 +1,33 @@ +.. + Copyright 2014 IBM Corp. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. _identifiers: + +============ + Identifiers +============ + +This specification defines an Identifier type that is based upon the Uniform +Resource Identifier Reference (URI) as specified in RFC3986. Any value that +represents a CADF Identifier type in this specification, its extensions, or +profiles SHALL adhere to the requirements listed in this section: + +.. note:: + + CADF Identifier type values SHALL be created to be Universally Unique + Identifiers (UUIDs) so that when CADF data (e.g., CADF Event Records, Logs, + Reports, Resources, Metrics, etc.) are federated it will be uniquely + identifiable to the source (e.g., cloud provider, service, etc.) that + created them. diff --git a/doc/source/specification/index.rst b/doc/source/specification/index.rst new file mode 100644 index 0000000..56d2e06 --- /dev/null +++ b/doc/source/specification/index.rst @@ -0,0 +1,28 @@ +============== + Specification +============== + +The following is a high-level description of the CADF specification. The basic +component of the CADF spec are Events. The full CADF specification document +can be found here_. + +.. _here: http://www.dmtf.org/standards/cadf + +.. toctree:: + :maxdepth: 2 + + events + attachments + credentials + endpoints + geolocations + hosts + identifiers + measurements + paths + reasons + reportersteps + resources + tags + timestamps + taxonomy diff --git a/doc/source/specification/measurements.rst b/doc/source/specification/measurements.rst new file mode 100644 index 0000000..afbea8d --- /dev/null +++ b/doc/source/specification/measurements.rst @@ -0,0 +1,77 @@ +.. + Copyright 2014 IBM Corp. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. _measurements: + +============= + Measurements +============= + +A component that contains statistical or measurement information for TARGET +resources that are being monitored. The measurement should be based upon a +defined metric (a method of measurement). + +============ =============== ========= ================================================================================================================= +Property Type Required Description +============ =============== ========= ================================================================================================================= +result xs:any Yes The quantitative or qualitative result of a measurement from applying the associated metric +metric cadf:Metric Dependent The property describes the metric used in generating the measurement result. Required if not metricId +metricId cadf:Identifier Dependent This property identifies a CADF Metric by reference and whose definition exists elsewhere. Required if not metric +calculatedBy cadf:Resource No An optional description of the resource that calculated the measurement +============ =============== ========= ================================================================================================================= + +Metrics +======= + +The Metric data type describes the rules and processes for measuring some +activity or resource, resulting in the generation of some values (captured by +the Measurement type). + +=========== =============== ======== ================================================== +Property Type Required Description +=========== =============== ======== ================================================== +metricId cadf:identifier Yes The identifier for the metric. +unit xs:string Yes The metrics unit (e.g., "ms", "Hz", "GB", etc.) +name xs:string No A descriptive name for metric +annotations cadf:map No User-defined metric information. +=========== =============== ======== ================================================== + +Serialisation +============= + +json:: + + { + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/log", + ..., + "metrics": [ + { + "metricId": "myuuid://metric.org/1234", + "unit": "GB", + "name": "Storage Capacity in Gigabytes" + }], + ..., + "events": [ + { + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + ..., + "measurements": [ + { + "result": "10", + "metricId": "myuuid://metric.org/1234" + }], + ... + }] + } diff --git a/doc/source/specification/paths.rst b/doc/source/specification/paths.rst new file mode 100644 index 0000000..ad9a063 --- /dev/null +++ b/doc/source/specification/paths.rst @@ -0,0 +1,25 @@ +.. + Copyright 2014 IBM Corp. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. _paths: + +====== + Paths +====== + +This clause describes how to represent values that are elements of hierarchies. +This construct is used for example when providing values from CADF Taxonomies +that classify components of the CADF Event Model within CADF Event Records as +path values. diff --git a/doc/source/specification/reasons.rst b/doc/source/specification/reasons.rst new file mode 100644 index 0000000..aed4e20 --- /dev/null +++ b/doc/source/specification/reasons.rst @@ -0,0 +1,49 @@ +.. + Copyright 2014 IBM Corp. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. _reasons: + +======== + Reasons +======== + +A component that contains a means to provide additional details and further +classify the top-level OUTCOME of the ACTION included in a CADF Event Record. + +========== ========= ======== ===================================================================================================================== +Property Type Required Description +========== ========= ======== ===================================================================================================================== +reasonType xs:anyURI No The domain URI that defines the "reasonCode" property's value +reasonCode xs:string No An optional detailed result code as described by the domain identified in the "reasonType" property +policyType xs:anyURI No The domain URI that defines the "policyId" property’s value +policyId xs:string No An optional identifier that indicates which policy or algorithm was applied in order to achieve the described OUTCOME +========== ========= ======== ===================================================================================================================== + +Serialisation +============= + +json:: + + { + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + ..., + "reason": { + "reasonType": "http://www.iana.org/assignments/http-status-codes/http-status-codes.xml", + "reasonCode": "408", + "policyType": "http://schemas.xmlsoap.org/ws/2002/12/policy", + "policyId": "http://10.0.3.4/firewall-ruleset/rule0012" + }, + ... + } diff --git a/doc/source/specification/reportersteps.rst b/doc/source/specification/reportersteps.rst new file mode 100644 index 0000000..40bbf26 --- /dev/null +++ b/doc/source/specification/reportersteps.rst @@ -0,0 +1,60 @@ +.. + Copyright 2014 IBM Corp. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. _reportersteps: + +============== + Reportersteps +============== + +This type represents a step in the REPORTERCHAIN that captures information +about any notable REPORTER (in addition to the OBSERVER) that modified or +relayed the CADF Event Record and any details regarding any modification it +performed on the CADF Event Record it is contained within. + +The Reporterstep data type should capture information about the resources that +have had a role in modifying, or relaying the CADF Event Record during its +lifecycle after having been created by the OBSERVER. + +============ ================= ========= ========================================================================================================================== +Property Type Required Description +============ ================= ========= ========================================================================================================================== +role xs:string Yes The role the REPORTER performed on the CADF Event Record (e.g., an "observer", "modifier" or "relay" role) +reporter cadf:Resource Dependent This property defines the resource that acted as a REPORTER on a CADF Event Record. Required if not reporterId +reporterId cadf:Identifier Dependent This property identifies a resource that acted as a REPORTER on a CADF Event Record by reference. Required if not reporter +reporterTime cadf:Timestamp No The time a REPORTER adds its Reporterstep entry into the REPORTERCHAIN +attachments cadf:Attachment[] No An optional array of additional data containing information about the reporter or any action it performed +============ ================= ========= ========================================================================================================================== + +Serialisation +============= + +json:: + + { + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + ..., + "reporterchain": [ + { + "role": "modifier", + "reporterTime": "2012-03-22T13:00:00-04:00", + "reporter": { + "id": "myscheme://mydomain/resource/monitor/id/0002" + } + }, + ... + ] + } + diff --git a/doc/source/specification/resources.rst b/doc/source/specification/resources.rst new file mode 100644 index 0000000..9225baa --- /dev/null +++ b/doc/source/specification/resources.rst @@ -0,0 +1,64 @@ +.. + Copyright 2014 IBM Corp. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. _resources: + +========== + Resources +========== + +Resources in general can be used to describe traditional IT components +(e.g., servers, network devices, etc.), software components +(e.g., platforms, databases, applications, etc.), operational and business +data (e.g., accounts, users, etc.) and roles, which can be assigned to +persons, that describe the authority to access capabilities. + +============= ================= ========= =================================================================================================================================== +Property Type Required Description +============= ================= ========= =================================================================================================================================== +id cadf:Identifier Yes The identifier for the resource +typeURI cadf:Path Yes The classification (i.e., type) of the resource using the CADF Resource Taxonomy +name xs:string No The optional local name for the resource (not necessarily unique) +domain xs:string No The optional name of the domain that qualifies the name of the resource +credential cadf:Credential No The optional security credentials associated with the resource’s identity +addresses cadf:Endpoint[] No The optional descriptive addresses (including URLs) of the resource +host cadf:Host No The optional information about the (network) host of the resource +geolocation cadf:Geolocation Dependent This optional property describes the geographic location of the resource using Geolocation data type. Required if not geolocationId +geolocationId cadf:Identifier Dependent This optional property identifies a CADF Geolocation by reference. Required if not geolocation +attachments cadf:Attachment[] No An optional array of extended or domain-specific information about the resource or its contex +============= ================= ========= =================================================================================================================================== + +Serialisation +============= + +json:: + + { + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + ..., + "target": { + "id": "myscheme://mydomain/resource/id/0001", + "typeURI": "service/compute", + "name": "server_0001", + ..., + "geolocation": { + "city": "Austin", + "state": "TX", + "regionICANN": "US" + } + } + } + + diff --git a/doc/source/specification/tags.rst b/doc/source/specification/tags.rst new file mode 100644 index 0000000..9a67353 --- /dev/null +++ b/doc/source/specification/tags.rst @@ -0,0 +1,29 @@ +.. + Copyright 2014 IBM Corp. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. _tags: + +===== + Tags +===== + +A "tag" is a label that can be added to a CADF Event Record to qualify or +categorize an event. + +Tags provide a powerful mechanism for adding domain-specific identifiers and +classifications to CADF Event Records that can be referenced by the CADF Query +Interface. This allows customers to construct custom reports or views on the +event data held by a provider for a specific domain of interest. A CADF Event +Record can have multiple tags that enable cross-domain analysis. \ No newline at end of file diff --git a/doc/source/specification/taxonomy.rst b/doc/source/specification/taxonomy.rst new file mode 100644 index 0000000..185ea27 --- /dev/null +++ b/doc/source/specification/taxonomy.rst @@ -0,0 +1,33 @@ +.. + Copyright 2014 IBM Corp. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. _taxonomy: + +========= + Taxonomy +========= + +The CADF Resource Taxonomy describes resources that are commonly used in cloud +and enterprise infrastructures. This list was developed based on surveys of +existing cloud architectures, deployments, and implementations. The Resource +Taxonomy, however, is fully intended to be extensible by profiles that may +define additional resource nodes as child nodes to the ones specified below. +When doing so, however, vendors and cloud providers should be aware that this +places an additional burden on the consumer to correctly comprehend the new +node type. Therefore, vendors and providers of CADF audit data should be +careful to provide classification values that extend the existing tree from the +most granular node that closely matches the functions of any newly-defined +resource types. This approach will provide consumers with a baseline +understanding of the function of the new resource type. \ No newline at end of file diff --git a/doc/source/specification/timestamps.rst b/doc/source/specification/timestamps.rst new file mode 100644 index 0000000..d5f964f --- /dev/null +++ b/doc/source/specification/timestamps.rst @@ -0,0 +1,34 @@ +.. + Copyright 2014 IBM Corp. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. _timestamps: + +=========== + Timestamps +=========== + +The following example shows the required Lexical representation of the +Timestamp type used in this specification; all Timestamp typed values +SHALL be formatted accordingly: + +:: + + yyyy '-' mm '-' dd 'T' hh ':' mm ':' ss ('.' s+)('+' | '-') hh ':' mm + +.. note:: + + The UTC offset is always required (not optional) and the use of the + character 'Z' (or 'Zulu' time) as an abbreviation for UTC offset +00:00 + or -00:00 is NOT permitted. \ No newline at end of file -- cgit v1.2.1