Bug 722915 - AppArmor documentation outdated
AppArmor documentation outdated
Status: VERIFIED FIXED
Classification: openSUSE
Product: openSUSE 12.2
Classification: openSUSE
Component: Documentation
Factory
Other Other
: P5 - None : Normal (vote)
: ---
Assigned To: Tomáš Bažant
Karl Eichwalder
:
Depends on:
Blocks:
  Show dependency treegraph
 
Reported: 2011-10-09 23:41 UTC by Christian Boltz
Modified: 2014-03-10 14:26 UTC (History)
0 users

See Also:
Found By: ---
Services Priority:
Business Priority:
Blocker: ---
Marketing QA Status: ---
IT Deployment: ---


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Christian Boltz 2011-10-09 23:41:07 UTC
I just noticed that the AppArmor documentation in the security guide is outdated.

http://doc.opensuse.org/products/opensuse/openSUSE/opensuse-security/cha.apparmor.start.html

"18.5. Configuring Novell AppArmor Event Notification and Reports"

Please hide this section - reporting is not available in 12.1 (aa-eventd isn't maintained upstream, and doesn't understand the (not-so-)new audit.log format)

http://doc.opensuse.org/products/opensuse/openSUSE/opensuse-security/cha.apparmor.profiles.html

"20.11. Setting Capabilities per Profile"

"set capabilities" was dropped upstream - please remove this section

http://doc.opensuse.org/products/opensuse/openSUSE/opensuse-security/cha.apparmor.repos.html

The online profile repository is disabled by default now - therefore most of this chapter should be hidden. The local profile repository /etc/apparmor/profiles/extras still exists.

http://doc.opensuse.org/products/opensuse/openSUSE/opensuse-security/cha.apparmor.yast.html

"22.5. Updating Profiles from Log Entries"
The box "Support for the External Profile Repository" should be hidden.

"22.6. Managing Novell AppArmor and Security Event Status"
Event notification depends on the (unmaintained) aa-eventd - please remove the parts about notification. You might also want to create a new screenshot.

http://doc.opensuse.org/products/opensuse/openSUSE/opensuse-security/cha.apparmor.commandline.html#sec.apparmor.commandline.profiling.summary.logprof
has another reference to the online profile repo.

http://doc.opensuse.org/products/opensuse/openSUSE/opensuse-security/cha.apparmor.managing.html
"26.1. Monitoring Your Secured Applications"
"26.2. Configuring Security Event Notification"
"26.3. Configuring Reports"
are all about reports, which depend on aa-eventd and are not available in 12.1. Please hide those sections.

26.4. Configuring and Using the AppArmor Desktop Monitor Applet
The Gnome desktop applet is obsolete. It was replaced by aa-notify, which can be started with:
    sudo DISPLAY=$DISPLAY /usr/sbin/aa-notify -p
You also have to edit /etc/apparmor/notify.conf - change use_group to a group where your user is a member.

BTW: the need for handing over $DISPLAY is caused by the very secure sudo config in openSUSE - it resets most environment variables. Maybe I get a more user-friendly way implemented upstream, but I'm afraid you'll always have to hand over $DISPLAY (or $DBUS_SESSION_BUS_ADDRESS) to 
aa-notify.
Yes, I'm aware that this isn't a perfect solution, but it's the best I can offer for 12.1.

http://doc.opensuse.org/products/opensuse/openSUSE/opensuse-security/cha.apparmor.support.html
"27.4.5. Why are the Reports not Sent by E-Mail?"
Another usage of aa-eventd - please hide.


So far, so good. That was enough text to hide (don't delete it, reporting might come back and then you can re-use it ;-)


There are also several things that need to be changed/updated:

http://doc.opensuse.org/products/opensuse/openSUSE/opensuse-security/cha.apparmor.support.html
contains several outdated links:
- http://www.novell.com/linux/security/apparmor//
  now redirects to a general page about security.
  Please change it to http://wiki.apparmor.net
- http://www.novell.com/documentation/apparmor/
  contains terribly outdated documentation because the apparmor guid was merged 
  into the security guide. Please change the link to the security guide.
- the mailinglists have been merged into one and moved to
  https://lists.ubuntu.com/mailman/listinfo/apparmor

http://doc.opensuse.org/products/opensuse/openSUSE/opensuse-security/cha.apparmor.intro.html#sec.apparmor.intro.background
http://en.opensuse.org/AppArmor_Geeks has been moved to http://en.opensuse.org/SDB:AppArmor_geeks

http://doc.opensuse.org/products/opensuse/openSUSE/opensuse-security/cha.apparmor.support.html
"27.4.6. How to Exclude Certain Profiles from the List of Profiles Used?"
There's an easier way now - run "aa-disable". It will create a symlink in /etc/apparmor.d/disable. To re-enable the profile, delete the symlink.
(This method has the advantage that a profile doesn't reappear after updating the apparmor-profiles package.)

"27.4.8. How to Spot and fix AppArmor Syntax Errors?"
Additional method: Open the buggy profile in vi. The syntax highlighting will mark lines with syntax errors with red background.


And finally there are some things that are not documented yet:

aa-notify partly replaces aa-eventd - besides the desktop notification, it can print reports based on the audit.log. This can also be used to mail daily reports by using
    aa-notify -s 1 -v | mail -s 'AppArmor report' user@host
in a cronjob.

http://doc.opensuse.org/products/opensuse/openSUSE/opensuse-security/cha.apparmor.commandline.html
does not mention the "cx" (execute in child profile) permissions, and maybe other new profile rules.

There are probably some more things the documentation doesn't cover yet. See
http://wiki.apparmor.net/index.php/ReleaseNotes_2_4
http://wiki.apparmor.net/index.php/ReleaseNotes_2_5
http://wiki.apparmor.net/index.php/ReleaseNotes_2_6
http://wiki.apparmor.net/index.php/ReleaseNotes_2_7
for the changelogs.


If you have questions, feel free to ask ;-)
Comment 1 Frank Sundermeyer 2011-11-14 12:11:34 UTC
Updated the AppaArmor docs with all teh FIXMEs from above:


http://doc.opensuse.org/products/draft/openSUSE_Factory/opensuse-security_sd_draft/part.apparmor.html

However, the TODOs still need to be done (in early 2012), therefore will not change the bug's status.
Comment 2 Christian Boltz 2012-06-11 17:25:47 UTC
openSUSE 12.2 will contain AppArmor 2.8, which brings two new utilities:
- aa-exec utility to launch programs under a specific profile
- aa-easyprof templated profile generation tool

See http://wiki.apparmor.net/index.php/ReleaseNotes_2_8 for all changes - there are some additions to the profile language (mount rules and the file keyword).
Comment 3 Tomáš Bažant 2014-01-14 15:40:05 UTC
I included/updated most of the changes in AppArmor up till version 2.8.
All important are described and referenced in the file https://svn.opensuse.org/svn/opensuse-doc/trunk/documents/sle/en/xml/security_docupdates.xml

If you're not fine with svn , i can send you a pdf instead.
Let me know if it's ok or what to add/change.
Comment 4 Christian Boltz 2014-02-01 21:25:24 UTC
resetting needinfo - I mailed you the review about two weeks ago. Feel free to ask for another review when you have an updated version.
Comment 5 Tomáš Bažant 2014-03-10 14:26:14 UTC
i believe the many reviews were very useful and lead to closing this bug, thanks christian!