Subject: [sacm] Use Cases Style

From: "David Harrington" <[email-masked]>
Date: Sun, 21 Jul 2013 15:37:17 -0400

Hi,

There has been some debate about the amount of detail and the formality of
the format used in our use cases document.

I have argued for IETF-style use cases; Adam has argued for a systems
engineering style, recommending the Martin Fowler format.

The IETF approach:

I recommended that people look at other IETF Use Case documents to see what
is "normal" for IETF use case documents.

Knowing that everybody is busy, I assumed few if any would actually do so.

So to move the discussion forward, I searched for RFCs with "Use Case" in
the title.

Then  I looked at each, and copied a quote from the text about the purpose
of each document (where available)

I then copied in a sample use case from each document.

I was planning to make these into a PowerPoint presentation (I expected that
would be very hard to do, given the space limitations of a slide).

So I chose short examples.

Feel free to look at longer examples if you want.

My samples of IETF use cases are in the attached file.

The usability.gov approach
(http://www.usability.gov/how-to-and-tools/methods/use-cases.html)

Elements of a Use Case

Depending on how in depth and complex you want or need to get, use cases
describe a combination of the following elements:

.Actor - anyone or anything that performs a behavior (who is using the
system)

.Stakeholder - someone or something with vested interests in the behavior of
the system under discussion (SUD)

.Primary Actor - stakeholder who initiates an interaction with the system to
achieve a goal

.Preconditions - what must be true or happen before and after the use case
runs.

.Triggers - this is the event that causes the use case to be initiated.

.Main success scenarios [Basic Flow] - use case in which nothing goes wrong.

.Alternative paths [Alternative Flow] - these paths are a variation on the
main theme. These exceptions are what happen when things go wrong at the
system level.

How To Write a Use Case

Write the steps in a use case in an easy-to-understand narrative. Kenworthy
(1997) outlines the following steps:

1.       Identify who is going to be using the website.

2.       Pick one of those users.

3.       Define what that user wants to do on the site. Each thing the use
does on the site becomes a use case.

4.       For each use case, decide on the normal course of events when that
user is using the site.

5.       Describe the basic course in the description for the use case.
Describe it in terms of what the user does and what the system does in
response that the user should be aware of.

6.       When the basic course is described, consider alternate courses of
events and add those to "extend" the use case.

7.       Look for commonalities among the use cases. Extract these and note
them as common course use cases.

8.       Repeat the steps 2 through 7 for all other users.

Middleweight Laundry Use Case

Use Case 1: Do laundry 

Actor: Housekeeper 

Basic Flow: On Wednesdays, the housekeeper reports to the laundry room.  She
sorts the laundry that is there.  Then she washes each load.  She dries each
load. She folds the items that need folding.  She throws away any laundry
item that is irrevocably shrunken, soiled or scorched. 

Alternative Flow 1: If she notices that something is wrinkled, she irons it
and then hangs it on a hanger. 

Alternative Flow 2: If she notices that something is still dirty, she
rewashes it. 

Alternative Flow 3: If she notices that something shrank, she throws it out.

Adam's example use case:

Use Case Name: Suspicious Endpoint Behavior

Description: 

This Use Case describes the collaboration between specific participants in
an information security system specific to detecting a connection attempt to
a known-bad Internet host by a botnet zombie that has made its way onto an
organization's Information Technology systems.  The primary human actor is
the Security Operations Center Analyst, and the primary software actor is
the configuration assessment tool.  Note, however, the dependencies on other
tools, such as asset management, intrusion detection, and messaging.

Actors: 

   * Security Operations Center (SOC) Analyst, 

   * Information Security Officer, 

   * System Owner

   * Organizational Unit Leader

Preconditions:

   * Organizational Security Policy Exists

   * Security Policy specifies appropriate asset management capabilities
(i.e. categorization of endpoints)

   * Security Policy specifies endpoint configuration baseline for asset
categorization

   * The Organization keeps a list of known-bad Internet hosts

   * The Organization associates owners who are individuals with endpoints

   * The Organization associates organizational units with endpoints

Postconditions:

   * Endpoint configuration has been assessed [1]

   * Results have been conveyed to scan requester

Primary Path:

  1. At 03:46 UTC an organization's Network Intrusion Detection System
(NIDS) sees an IP packet with a destination IPv6 address existing on a
blacklist of known botnet command and control (C2) servers.

  2. The NIDS sends an alert to the SOC Analyst.

  3. The SOC Analyst uses the information captured in the alert (IP packet
and reason for the flag) to look up the endpoint in the organization's asset
inventory system and discovers that the endpoint is a Windows Server 2008 R2
Member Server playing the role of a File Server

  4. The SOC Analyst also verifies that the IPv6 address cited by the NIDS
is, in fact, on the blacklist for known C2 servers.

  5. At this point, the SOC Analyst switches over to the organization's
configuration assessment tool

  6. The SOC Analyst locates the offending endpoint in the configuration
assessment tool's endpoint catalog [2]

  7. The SOC Analyst then initiates an immediate and complete endpoint
assessment to determine if the endpoint has experienced any configuration
drift [3].

  8. The configuration assessment tool:

  9. 

    a. Performs a preliminary asset inventory scan on the offending
endpoint, which results in a list of installed software [4][5]

    b. Performs a comparison between the last known asset inventory and the
present asset inventory and notes any differences

    c. Searches it's local content repository for appropriate configuration
baselines for the operating system of the offending endpoint and for each
installed piece of software

    d. Upon aggregating the set of applicable configuration baselines, the
configuration assessment tool then connects to and queries the
organization's configuration content repository for newer baselines that may
exist.

    e. If a new baseline exists, then it is returned by the configuration
content repository.

  10. The configuration management tool, having the set of updated
baselines, initiates a scan against the offending host, which yields a
result set.

  11. The configuration management tool displays scan results to the SOC
Analyst, which show that three new pieces of software have been installed on
the offending endpoint where one piece of software is not on the authorized
software list, and that several configuration items were out of compliance
with the organization's established baselines.

  12. The SOC Analyst reviews the information for accuracy and to plan next
steps before sending the report to the responsible Information Security
Officer, accountable System Owner, and the Organizational Unit Leader.

A Note On Alternative Paths, Preconditions, and Postconditions:

There are likely to be many points of optimization and optional paths.  For
example, a configuration assessment tool might provide a "quick glance" look
at the most recent scan history for the offending endpoint.  A SOC Analyst
might then elect not to run a new scan (i.e. the offending endpoint is known
to be out of compliance, so why run a new scan?).  Another point might be
that the offending endpoint is, at present, not authorized to be on the
network, in which case it is very likely not to exist in the configuration
assessment tool's endpoint catalog.

As with alternative paths, pre-/post-conditions can vary widely.  Consider
that this description likely represents an organization on the mature side
of managing information security.  Many organizations do not have a Security
Operations Center, nor do they necessarily monitor their network.  It may be
the case that a log management process has detected the blacklisted
connection attempt  through audit trail monitoring.  Or, it may be the case
that a shared indicator of compromise has been used to detect the offending
endpoint.

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

[1] I am assuming at this point that "configuration assessment" has been
defined and will be understood by the reader.  What I consider to be
"assessment" is that the baseline has been obtained, send to the scanning
implementation, endpoint configuration item values have been harvested,
endpoint configuration item values have been compared against baseline, and
results stored/forwarded as appropriate for the use case.

[2] An "endpoint catalog" is intended to convey nothing more than the notion
that configuration assessment tools are likely to have some method of
listing, enumerating, or aggregating endpoints under configuration
management. 

[3] It may not be necessary to specify what we mean by "complete" or the
order in which scanning operations take place.  In this particular scenario,
I thought it might be useful to illustrate that "scan levels" exist on a
continuum.  

[4] Remember that the configuration assessment tool has knowledge of the
offending endpoint so running a preliminary inventory scan is reasonable at
this point.

[5] The mechanism of scan could be agent-based or remote, so details of how
a scan happens are omitted here.  A more granular partition of the process
is required for further details.

This message and attachments may contain confidential information.  If it
appears that this message was sent to you by mistake, any retention,
dissemination, distribution or copying of this message and attachments is
strictly prohibited.  Please notify the sender immediately and permanently
delete the message and any attachments.

My Comments:

Executive Summary:

The IETF format is what most IETF readers will expect. This format has the
drawback of not being formal, and is not necessarily very complete. If we to
derive requirements from this freehand format, it can be more difficult. But
it is easily readable, so reviewers of our work can understand what we are
trying to accomplish. Use cases of this form help to identify the nature of
the stakeholders involved in our WG. Operators vs vendors, service providers
vs enterprises, managed-device implementers vs management application
developers, and so on. This can help to categorize requirements that exist
for some stakeholders but not all stakeholders.

I think the formal approach recommended in usability.gov would be more work
for the editors to lay out the use cases in this formal format, and the
ASCII text required for RFCs makes this much harder than, say Word or HTML
formats.

Usability.gov step 2 says "pick one of the users" to document as the actor.
Each thing the user wants to do becomes a use case, and each possible
alternative action becomes a use case.

Adam's example for Actor includes multiple roles, and then describes a
rather complex use case , including footnotes.

Part of my concern is that we have WG contributors coming from multiple
vendors, with possibly multiple products, representing customers from
multiple industry segments.

To fully detail each possible alternative would make it close to impossible
to actually finish this document in a reasonable amount of time.

I suspect Adam combined a number of use cases together in his example, to
simplify things.

However, I cannot figure out how to create English sentences from his
example because he has multiple actors and multiple preconditions and
multiple postconditions, and what seems to be a lot of irrelevant details in
the Primary Path. Is the fact that this happens at 3:46 UTC an important
detail in our design? Or is it an irrelevant detail? Or is it important for
some use cases (such as trying to establish behavior anomalies based on when
a user normally works, or when an attack normally happens?) but not others? 

I think the formal approach is over the top for our needs.

The IETF approach seems more appropriate at this point in our work process.

David Harrington

[email-masked]

+1-603-828-1401

---

From: "Romascanu, Dan (Dan)" <[email-masked]>
Date: Thu, 25 Jul 2013 13:40:55 +0000

Hi,

I am certainly culturally biased in this dispute for the very simple and obvious reason that I have spent too much time in the IETF and too little to zero time in other security-oriented organizations, so I am familiar with the 'IETF approach' while the 'usability.gov approach' seems strange to me.

I do have however one question that seems to me to go beyond the 'style' issues. The usability.gov examples include definition and actions (procedures) executed by actors who are I believe what we call in IETF terms 'human operators' using the network and the systems. It is very seldom that the IETF defines anything that deals with human operators actions in standards-track documents. At most we may make operational recommendations, never beyond the BCP level.

Maybe this discussion is useful to clarify the use cases, but I do not see how the 'actors' actions fit into the current WG charter. Am I mistaken? Do I miss something important?

Thanks and Regards,

Dan

From: [email-masked] [mailto:[email-masked]] On Behalf Of David Harrington
Sent: Sunday, July 21, 2013 10:37 PM
To: [email-masked]
Subject: [sacm] Use Cases Style

Hi,

There has been some debate about the amount of detail and the formality of the format used in our use cases document.

I have argued for IETF-style use cases; Adam has argued for a systems engineering style, recommending the Martin Fowler format.

The IETF approach:

I recommended that people look at other IETF Use Case documents to see what is "normal" for IETF use case documents.

So to move the discussion forward, I searched for RFCs with "Use Case" in the title.

Then  I looked at each, and copied a quote from the text about the purpose of each document (where available)

I was planning to make these into a PowerPoint presentation (I expected that would be very hard to do, given the space limitations of a slide).

The usability.gov approach (http://www.usability.gov/how-to-and-tools/methods/use-cases.html)

Elements of a Use Case

Depending on how in depth and complex you want or need to get, use cases describe a combination of the following elements:

*Actor - anyone or anything that performs a behavior (who is using the system)

*Stakeholder - someone or something with vested interests in the behavior of the system under discussion (SUD)

*Primary Actor - stakeholder who initiates an interaction with the system to achieve a goal

*Preconditions - what must be true or happen before and after the use case runs.

*Triggers - this is the event that causes the use case to be initiated.

*Main success scenarios [Basic Flow] - use case in which nothing goes wrong.

*Alternative paths [Alternative Flow] - these paths are a variation on the main theme. These exceptions are what happen when things go wrong at the system level.

How To Write a Use Case

Write the steps in a use case in an easy-to-understand narrative. Kenworthy (1997) outlines the following steps:

3.       Define what that user wants to do on the site. Each thing the use does on the site becomes a use case.

4.       For each use case, decide on the normal course of events when that user is using the site.

5.       Describe the basic course in the description for the use case. Describe it in terms of what the user does and what the system does in response that the user should be aware of.

6.       When the basic course is described, consider alternate courses of events and add those to "extend" the use case.

7.       Look for commonalities among the use cases. Extract these and note them as common course use cases.

Use Case 1: Do laundry

Actor: Housekeeper

Basic Flow: On Wednesdays, the housekeeper reports to the laundry room.  She sorts the laundry that is there.  Then she washes each load.  She dries each load. She folds the items that need folding.  She throws away any laundry item that is irrevocably shrunken, soiled or scorched.

Alternative Flow 1: If she notices that something is wrinkled, she irons it and then hangs it on a hanger.

Alternative Flow 2: If she notices that something is still dirty, she rewashes it.

Adam's example use case:

Description:

This Use Case describes the collaboration between specific participants in an information security system specific to detecting a connection attempt to a known-bad Internet host by a botnet zombie that has made its way onto an organization's Information Technology systems.  The primary human actor is the Security Operations Center Analyst, and the primary software actor is the configuration assessment tool.  Note, however, the dependencies on other tools, such as asset management, intrusion detection, and messaging.

Actors:

   * System Owner

Preconditions:

   * Security Policy specifies appropriate asset management capabilities (i.e. categorization of endpoints)

   * Security Policy specifies endpoint configuration baseline for asset categorization

Postconditions:

Primary Path:

  1. At 03:46 UTC an organization's Network Intrusion Detection System (NIDS) sees an IP packet with a destination IPv6 address existing on a blacklist of known botnet command and control (C2) servers.

  3. The SOC Analyst uses the information captured in the alert (IP packet and reason for the flag) to look up the endpoint in the organization's asset inventory system and discovers that the endpoint is a Windows Server 2008 R2 Member Server playing the role of a File Server

  4. The SOC Analyst also verifies that the IPv6 address cited by the NIDS is, in fact, on the blacklist for known C2 servers.

  5. At this point, the SOC Analyst switches over to the organization's configuration assessment tool

  6. The SOC Analyst locates the offending endpoint in the configuration assessment tool's endpoint catalog [2]

  7. The SOC Analyst then initiates an immediate and complete endpoint assessment to determine if the endpoint has experienced any configuration drift [3].

  9.

    a. Performs a preliminary asset inventory scan on the offending endpoint, which results in a list of installed software [4][5]

    b. Performs a comparison between the last known asset inventory and the present asset inventory and notes any differences

    c. Searches it's local content repository for appropriate configuration baselines for the operating system of the offending endpoint and for each installed piece of software

    d. Upon aggregating the set of applicable configuration baselines, the configuration assessment tool then connects to and queries the organization's configuration content repository for newer baselines that may exist.

    e. If a new baseline exists, then it is returned by the configuration content repository.

  10. The configuration management tool, having the set of updated baselines, initiates a scan against the offending host, which yields a result set.

  11. The configuration management tool displays scan results to the SOC Analyst, which show that three new pieces of software have been installed on the offending endpoint where one piece of software is not on the authorized software list, and that several configuration items were out of compliance with the organization's established baselines.

  12. The SOC Analyst reviews the information for accuracy and to plan next steps before sending the report to the responsible Information Security Officer, accountable System Owner, and the Organizational Unit Leader.

There are likely to be many points of optimization and optional paths.  For example, a configuration assessment tool might provide a "quick glance" look at the most recent scan history for the offending endpoint.  A SOC Analyst might then elect not to run a new scan (i.e. the offending endpoint is known to be out of compliance, so why run a new scan?).  Another point might be that the offending endpoint is, at present, not authorized to be on the network, in which case it is very likely not to exist in the configuration assessment tool's endpoint catalog.

As with alternative paths, pre-/post-conditions can vary widely.  Consider that this description likely represents an organization on the mature side of managing information security.  Many organizations do not have a Security Operations Center, nor do they necessarily monitor their network.  It may be the case that a log management process has detected the blacklisted connection attempt  through audit trail monitoring.  Or, it may be the case that a shared indicator of compromise has been used to detect the offending endpoint.

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

[1] I am assuming at this point that "configuration assessment" has been defined and will be understood by the reader.  What I consider to be "assessment" is that the baseline has been obtained, send to the scanning implementation, endpoint configuration item values have been harvested, endpoint configuration item values have been compared against baseline, and results stored/forwarded as appropriate for the use case.

[2] An "endpoint catalog" is intended to convey nothing more than the notion that configuration assessment tools are likely to have some method of listing, enumerating, or aggregating endpoints under configuration management.

[3] It may not be necessary to specify what we mean by "complete" or the order in which scanning operations take place.  In this particular scenario, I thought it might be useful to illustrate that "scan levels" exist on a continuum.

[4] Remember that the configuration assessment tool has knowledge of the offending endpoint so running a preliminary inventory scan is reasonable at this point.

[5] The mechanism of scan could be agent-based or remote, so details of how a scan happens are omitted here.  A more granular partition of the process is required for further details.

This message and attachments may contain confidential information.  If it appears that this message was sent to you by mistake, any retention, dissemination, distribution or copying of this message and attachments is strictly prohibited.  Please notify the sender immediately and permanently delete the message and any attachments.

My Comments:
Executive Summary:
The IETF format is what most IETF readers will expect. This format has the drawback of not being formal, and is not necessarily very complete. If we to derive requirements from this freehand format, it can be more difficult. But it is easily readable, so reviewers of our work can understand what we are trying to accomplish. Use cases of this form help to identify the nature of the stakeholders involved in our WG. Operators vs vendors, service providers vs enterprises, managed-device implementers vs management application developers, and so on. This can help to categorize requirements that exist for some stakeholders but not all stakeholders.

I think the formal approach recommended in usability.gov would be more work for the editors to lay out the use cases in this formal format, and the ASCII text required for RFCs makes this much harder than, say Word or HTML formats.
Usability.gov step 2 says "pick one of the users" to document as the actor. Each thing the user wants to do becomes a use case, and each possible alternative action becomes a use case.
Adam's example for Actor includes multiple roles, and then describes a rather complex use case , including footnotes.

Part of my concern is that we have WG contributors coming from multiple vendors, with possibly multiple products, representing customers from multiple industry segments.
To fully detail each possible alternative would make it close to impossible to actually finish this document in a reasonable amount of time.
I suspect Adam combined a number of use cases together in his example, to simplify things.
However, I cannot figure out how to create English sentences from his example because he has multiple actors and multiple preconditions and multiple postconditions, and what seems to be a lot of irrelevant details in the Primary Path. Is the fact that this happens at 3:46 UTC an important detail in our design? Or is it an irrelevant detail? Or is it important for some use cases (such as trying to establish behavior anomalies based on when a user normally works, or when an attack normally happens?) but not others?

David Harrington

[email-masked]<mailto:[email-masked]>

+1-603-828-1401

---

From: Stephen Hanna <[email-masked]>
Date: Wed, 31 Jul 2013 14:13:09 +0000

I should have responded to this thread earlier. I have been waiting to find enough time to write a long response as Dan did. However, it seems that I won't find that time before the SACM WG meeting so I'll just say:

I also favor the IETF approach to use case style: a brief summary of the problem to be solved.

In my view, providing a detailed walkthrough of the solution tends to restrict the architectural options. We're not ready for that yet. Instead, we should focus our use cases on the problem to be solved.

Thanks,

Steve

From: [email-masked]<mailto:[email-masked]> [mailto:[email-masked]] On Behalf Of Romascanu, Dan (Dan)
Sent: Thursday, July 25, 2013 9:41 AM
To: David Harrington; [email-masked]<mailto:[email-masked]>
Subject: Re: [sacm] Use Cases Style

Hi,

Thanks and Regards,

Dan

From: [email-masked]<mailto:[email-masked]> [mailto:[email-masked]] On Behalf Of David Harrington
Sent: Sunday, July 21, 2013 10:37 PM
To: [email-masked]<mailto:[email-masked]>
Subject: [sacm] Use Cases Style

Hi,

The IETF approach:

Elements of a Use Case

How To Write a Use Case

Use Case 1: Do laundry

Actor: Housekeeper

Adam's example use case:

Description:

Actors:

   * System Owner

Preconditions:

Postconditions:

Primary Path:

  9.

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

My Comments:
Executive Summary:

David Harrington

+1-603-828-1401