Making things more understandable

[Vladimir Giszpenc]

Hi all,

Developer Days are long gone, but I would like to propose another wacky
idea.  This is based on the assumption that people actually read the
descriptions which is a poor assumption but I am sticking to it.  One of
the goals of SCAP is "XCCDF should be structured to foster the
generation of readable prose documents from XCCDF-format documents."  We
could improve the descriptions of our rules (and some groups).

For example given:

      The <SERVICE NAME> service should be enabled or disabled as
appropriate.
        or
      The password minimum length should be set appropriately.

Could we instead have something like

      The <SERVICE NAME> service should be {some-var-id:selector}.
      or
      The password minimum length should be {some-other-var-id:value}.

The idea is to use either the selector or value chosen by the selected
profile.  We could default to something by convention and allow just
{some-var-id} to mean something.  I don't have a good story for
localized content.  If this idea has merit, we can try to think of
something better.  Making things complicated is usually a bad idea, but
it would make things a lot more readable.  This is an issue both in
XCCDF and OVAL (and all other checking systems).  Ideally, we could help
readability everywhere, but starting in XCCDF would be nice.

Besides the fact that changing anything is evil and the reality that
changing XCCDF is impossible, is this worth considering?


Thanks,

Vladimir Giszpenc
DSCI Contractor Supporting
US Army CERDEC S&TCD IAD Tactical Network Protection Branch
[phone]



---------------------------------------------------------------

To unsubscribe from this mailing list, please send an e-mail to
[hidden email] with the words "unsubscribe xccdf-dev" in the
body. You will need to send this from the email account that you
used to initially subscribe to xccdf-dev.

[bakerj]

Vlad,

I am glad you brought this up. We have had an internal discussion here at MITRE about how best to make rule descriptions meaningful in the Recommendation Tracker. Along the way it was brought to my attention that the capability I think you are describing is actually already built in to XCCDF.

Take a look at the xccdf definition of htmlTextWithSubType. I think that will get you pointed in the right direction in the xcdf spec. This capability will allow you to substitute values into the text of any element based on this type.


Jon

============================================
Jonathan O. Baker
G022 - IA Industry Collaboration
The MITRE Corporation
Email: [hidden email]

>-----Original Message-----
>From: [hidden email] [mailto:[hidden email]] On Behalf Of
>Vladimir Giszpenc
>Sent: Wednesday, July 08, 2009 9:13 AM
>To: Multiple recipients of list
>Subject: Making things more understandable
>
>
>Hi all,
>
>Developer Days are long gone, but I would like to propose another wacky
>idea.  This is based on the assumption that people actually read the
>descriptions which is a poor assumption but I am sticking to it.  One of
>the goals of SCAP is "XCCDF should be structured to foster the
>generation of readable prose documents from XCCDF-format documents."  We
>could improve the descriptions of our rules (and some groups).
>
>For example given:
>
>      The <SERVICE NAME> service should be enabled or disabled as
>appropriate.
> or
>      The password minimum length should be set appropriately.
>
>Could we instead have something like
>
>      The <SERVICE NAME> service should be {some-var-id:selector}.
>      or
>      The password minimum length should be {some-other-var-id:value}.
>
>The idea is to use either the selector or value chosen by the selected
>profile.  We could default to something by convention and allow just
>{some-var-id} to mean something.  I don't have a good story for
>localized content.  If this idea has merit, we can try to think of
>something better.  Making things complicated is usually a bad idea, but
>it would make things a lot more readable.  This is an issue both in
>XCCDF and OVAL (and all other checking systems).  Ideally, we could help
>readability everywhere, but starting in XCCDF would be nice.
>
>Besides the fact that changing anything is evil and the reality that
>changing XCCDF is impossible, is this worth considering?
>
>
>Thanks,
>
>Vladimir Giszpenc
>DSCI Contractor Supporting
>US Army CERDEC S&TCD IAD Tactical Network Protection Branch
>[phone]
>
>
>
>---------------------------------------------------------------
>
>To unsubscribe from this mailing list, please send an e-mail to
>[hidden email] with the words "unsubscribe xccdf-dev" in the
>body. You will need to send this from the email account that you
>used to initially subscribe to xccdf-dev.

---------------------------------------------------------------

To unsubscribe from this mailing list, please send an e-mail to
[hidden email] with the words "unsubscribe xccdf-dev" in the
body. You will need to send this from the email account that you
used to initially subscribe to xccdf-dev.

[Vladimir Giszpenc]

Thanks for the quick reply Jon.  

> I am glad you brought this up. We have had an internal discussion here
> at MITRE about how best to make rule descriptions meaningful in the
> Recommendation Tracker. Along the way it was brought to my attention
> that the capability I think you are describing is actually already
> built in to XCCDF.
>
> Take a look at the xccdf definition of htmlTextWithSubType. I think
> that will get you pointed in the right direction in the xcdf spec.
This
> capability will allow you to substitute values into the text of any
> element based on this type.

I still don't see how the substitution works.  This is not being served
up in some server scripting language.
How do I define the variable and get all XCCDF interpreters to do the
substitution the way I intend?

Let's say this is what htmlTextWithSubType looks like (please correct me
if I am wrong):

          <Rule id="some-rule-id" selected="false" weight="10.0">
            <title>Disable the foo Daemon </title>
            <description><xhtml:span xml:lang="en">The foo service
should be <sub idref="some-var-id"/>.</xhtml:span></description>


How will it show up as "...should be disabled." when rendered.  I can't
quite figure out how using XHTML gets me there.  I feel closer, but I
don't think we are quite there.  And the localization of variables is
still an issue (though I can live with it).

Don't we need something in the XCCDF specification to define how the
substitution must work?

Thanks again,


Vladimir Giszpenc
DSCI Contractor Supporting
US Army CERDEC S&TCD IAD Tactical Network Protection Branch
[phone]




---------------------------------------------------------------

To unsubscribe from this mailing list, please send an e-mail to
[hidden email] with the words "unsubscribe xccdf-dev" in the
body. You will need to send this from the email account that you
used to initially subscribe to xccdf-dev.

[Charles Schmidt (MITRE)]

Hello,

Jon is correct - I believe the XCCDF spec already has the functionality you describe.

>I still don't see how the substitution works.  This is not being served
>up in some server scripting language.

You are correct. The substitution is part of the XCCDF language itself. That is, an XCCDF interpreter or document generator would be responsible for performing the lookup and substitution. Basically, the substitution would be performed by similar mechanisms to those that provide Value values when exporting to a checking language via the <check-export> element.

>How do I define the variable and get all XCCDF interpreters to do the
>substitution the way I intend?

>Let's say this is what htmlTextWithSubType looks like (please correct me
>if I am wrong):
>
>          <Rule id="some-rule-id" selected="false" weight="10.0">
>            <title>Disable the foo Daemon </title>
>            <description><xhtml:span xml:lang="en">The foo service
>should be <sub idref="some-var-id"/>.</xhtml:span></description>
>
>
>How will it show up as "...should be disabled." when rendered.  I can't
>quite figure out how using XHTML gets me there.  I feel closer, but I
>don't think we are quite there.  And the localization of variables is
>still an issue (though I can live with it).

If there is a Value with id of "some-var-id" and title equal to "some var's title", and the currently selected value of this Value is "disabled", then the output will be something like "... should be some var's title(disabled)." The exact representation of the text that is substituted in is an implementation decision of the XCCDF interpreter that is performing the substitution. In fact, whether the currently selected value of the Value appears in the substitution is up to the interpreter writer. The only requirement is that the value of the <title> element of the referenced item replace the <sub> element in the text. (Note that a sub could reference any XCCDF Item, including Rules and Groups, in which case the respective <title> element would replace the <sub> element within the text.)

If you want the user to see "... should be disabled" (or more likely, something like "... should be (disabled)" since the spec requires that Value values be set off with an appropriate delimiter) just create a Value with an empty (0-length string) title and a value selected to "disabled". The second (much harder) step, is to find an XCCDF interpreter that 1) performs text substitution and 2) includes the currently selected Value value in these substitutions. I am not aware of any existing tools that perform 1, let alone 2. However, I admit to not being very familiar with the tools out there, so I may very well be mistaken on this. Any vendors out there who can correct me on this?

As for the localization issue - yes, that is an issue. In your example, you might want to use the xml:lang attribute of <description> rather than within the embedded XHTML. Regardless, the XCCDF spec makes no requirements as to how interpreters should handle lang attributes other than saying that it would be nice if they did.

>Don't we need something in the XCCDF specification to define how the
>substitution must work?

Page 37 and 38 of NIST IR 7275 provides the description of how substitution is supposed to work.

Will you be able to use this to meet your needs?

Charles
The MITRE Corp.


---------------------------------------------------------------

To unsubscribe from this mailing list, please send an e-mail to
[hidden email] with the words "unsubscribe xccdf-dev" in the
body. You will need to send this from the email account that you
used to initially subscribe to xccdf-dev.

[Gary Gapinski-4]

Some javascript/style in this post has been disabled (why?)

Hello, Vlad:

Vladimir Giszpenc wrote:

I still don't see how the substitution works.  This is not being served
up in some server scripting language.
How do I define the variable and get all XCCDF interpreters to do the
substitution the way I intend?
  

About the best that can be obtained is to assume such interpreters adhere to the definition of the <sub> element NIST IR 7275r3 pp74). The schema does not restrict the target of a sub; the spec specifies it must be a <Value> or <plain-text> element. The spec also calls the target a "parameter value that may be set during tailoring", so it would appear that the target is only reified as the result of tailoring. And, it's not a variable as one might regard a <Value> used as a

Let's say this is what htmlTextWithSubType looks like (please correct me
if I am wrong):

          <Rule id="some-rule-id" selected="false" weight="10.0">
            <title>Disable the foo Daemon </title>
            <description><xhtml:span xml:lang="en">The foo service
should be <sub idref="some-var-id"/>.</xhtml:span></description>


How will it show up as "...should be disabled." when rendered.  I can't
quite figure out how using XHTML gets me there.  I feel closer, but I
don't think we are quite there.  And the localization of variables is
still an issue (though I can live with it).
  

XHTML doesn't; a rendering of the XCCDF document would have to transform the <xhtml:span> content, substituting the actual or derived value of the element referenced by the <sub> element. In the case of a reference to a <plain-text> element, this would simply be the text node(s) contained therein. Not so simple for a <Value> element, as the derived value is subject to "tailoring".

The simplest of circumstances would be to add

<plain-text id="some-var-id>disabled</plain-text>

which would work regardless of tailoring. Less simple might be

<Value id="some-var-id">
    <default>impertinent</default>
    <value selector="enabled">enabled</value>
    <value selector="disabled">disabled</value>
</Value>

which in the absence of <Value> <value> selection (tailoring does not necessarily entail selection) obviates any prosaic substitution other than perhaps "impertinent,enabled,disabled".

Don't we need something in the XCCDF specification to define how the
substitution must work?
  

I don't think so, but keep in mind that this substitution is not coerced by the schema to produce results prosaically correct with respect to <sub>-referenced <Value> usage within <check> constructs.

And, as Charles notes, forget about localization.

Regards,

Gary

--------------------------------------------------------------- To unsubscribe from this mailing list, please send an e-mail to [hidden email] with the words "unsubscribe xccdf-dev" in the body. You will need to send this from the email account that you used to initially subscribe to xccdf-dev.