English | Deutsch
Home »

OpenVAS Change Request #48: Define OMP and OAP in RelaxNG Schema Language

Status: Voted +5. Done: OpenVAS Manager and OpenVAS Administrator of OpenVAS-4 can provide the protocol specification via command "help".

Purpose

References

Rationale

Documenting OMP and OAP in a formal schema would help keeping the OMP and OAP documentation up to date. This would

Design and Implementation

For the schema syntax, Relax NG compact syntax (RNC) is proposed. While there are many other schema definition syntaxes (DTD, Relax NG normal syntax, XML Schema Definition, etc.) RNC has the benefits of being compact and easy to read. RNC uses some kind of Backus-Naur-Form (BNF), which many software developers should be used to.

If required, Relax NG compact syntax can be converted into DTD, Relax NG normal syntax or XML Schema Definition using the tool trang (or others). XML documents can be validated against Relax NG using e.g. libxml2 or emacs' nXML-mode. Syntax-highlighting can be done with e.g. Syntax-higlight.

Here is a simple RelaxNG example for the create_agent OMP command: 

  create_agent = element create_agent {
      elem.name,
      comment?,
      installer,
      howto_use?,
      howto_install?
      }
  installer     = element installer     { Base64.datatype }
  howto_use     = element howto_use     { text }
  howto_install = element howto_install { text }

And here is an example for the OAP get_settings_response:

get_settings = element get_settings { empty }

get_settings_response = element get_settings_response {
    Status.attribs,
    element scanner_settings {
        attribute sourcefile,
	attribute editable [ "0" | "1" ],
	setting.get
    }
setting.get = element setting {
    attribute name,
    text
    }
modify_settings = element modify_settings {
    setting.modify?
    }
setting.modify = element setting {
    element name { text },
    element value { text }
    }
  1. A draft version of omp-1.0.rnc exists, written by Hartmut Goebel (see attachment to this message on openvas-devel). As of this initial writing, this draft is known to be incomplete and erroneous. Developers of openvas-manager are requested to complete and correct this draft.
  2. A draft version of oap-1.0.rnc exists, written by Hartmut Goebel. This draft is quite complete yet. Nevertheless developers of openvas-administrator are requested to complete and correct this draft.

Suggested Changes

  1. A file omp-1.0.rnc will be added to openvas-manager. This file defines the schema syntax of OMP Version 1.0. Until OMP Version 1.0 has stabilised, this file has to be updated whenever the implementation changes. This has to be done by the developer implementing the change.
  2. A file oap-1.0.rnc will be added to openvas-administrator. This file defines the schema syntax of OAP Version 1.0. Until OAP Version 1.0 has stabilised, this file has to be updated whenever the implementation changes. This has to be done by the developer implementing the change.

Future directions

Matthew Mundell suggested to extend the RNG file to also describe the behaviour of the commands. So the RNG could replace the description in the CR. Maybe with Doxygen comments can be used for this.

Effects

This is a new component. No effects to any currently existing component.

History