[apparmor] PATCH: apparmor.d man page

[Christian Boltz]

Hello,

Am Donnerstag, 9. Juni 2016, 00:43:34 CEST schrieb John Johansen:
> On 06/07/2016 03:30 PM, Christian Boltz wrote:
> > Am Dienstag, 7. Juni 2016, 13:46:46 CEST schrieb John Johansen:

> >> +=head3 Profile Audit Flags
> >> +
> >> +=item B<audit>
> >> +places the profile in audit mode which will cause all allowed
> >> accesses to +be audited. This is equivalent to placing the audit
> > 
> > I'd say denied accesses (covered by a deny rule) will also be
> > audited, so please clarify this detail.
> 
> In fact they won't. I even double checked this in the code

That sounds like surprising behaviour (aka "bug") - can we change this, 
please?

I assume your statement is also valid for complain mode, which would 
make things even worse (deny rules are still enforced, but not audited).

> > Also, maybe s/audited/logged/ - or clarify what "audited" actually
> > means (the explanation should probably contain hints to audit.log,
> > dmesg and, as a fallback, syslog)
> 
> that feels like an entirely different section. As what AppArmor does
> for auditing/logging needs to be understood even with out this.

Good point, I'm looking forward to your patch for that ;-)

> >> qualifier on all +allow rules in the profile.
> >> +
> >> +=item B<debug>
> >> +obsoleted in apparmo 2.5 and may result in a parse error (tested
> >> on
> >> 2.8), +it will be reintroduced at some point in the future. See
> >> below
> >> I<Debugging + AppArmor Policy> for other options.
> > 
> > I'd guess nobody remembers this flag, so I wonder if we should
> > mention it at all.
> 
> I have pared it down to removed in apparmor 2.5, nothing about
> reintroducing it.

I'd completely drop it - I doubt someone out there remembers the list of 
valid flags in 2.5 ;-)  (subscribers on this mailinglist are not part of 
"out there"!)

> >> +=head3 Profile Mode Flags
> > 
> > Instead of the "conflicts with" notes on every mode, would a
> > paragraph saying
> > 
> >     The profile mode flags allow, complain, debug, enforce and kill
> >     conflict with each other, so you can't use more than one.
> > 
> > I'm not even sure if we need to name all the flags here because they
> > are listed below, so it could also be
> > 
> >     The profile mode flags conflict with each other, so you can't
> >     use
> >     more than one.
> > 
> > (Do we need to mention "or none"?)
> > 
> > With this, we could then change the "conflicts with" to
> > 
> >     conflicts with other profile mode flags
> > 
> > to make the manpage easier to read and easier to maintain (if we
> > ever
> > add another flag, we don't need to edit all
> 
> makes sense. Done

Not really, see the comments on v2.

> >> +=item B<allow> -- conflicts with complain, debug, enforce, kill
> >> +places the profile in allow mode which will cause all denied
> >> accesses +to be audited and allowed. Allow mode is similar to
> >> complain mode except +that explicitly denied accesses are also
> >> allowed.
> >> +
> >> +Not supported in versions before AppArmor 3.6
> > 
> > We should make clear that the version number is about the kernel
> > side - otherwise users will be completely confused if userspace is
> > still at 2.11 ;-)
> 
> well there was some email about bumping the userspace version

Right, I noticed it ;-)

> > Also, my testing shows that the 2.11 beta parser doesn't understand
> > the "allow" flag, so maybe we shouldn't document it yet? (Same
> > question for other flags, see below.)
> 
> it should land soon, but maybe we should let tyler add this blurb in
> his patches

Good idea.

> > BTW: The "stop" mode sounds like it could be useful for interactive
> > profile development - stop the process, ask about the access, update
> > the profile, continue the process.
> 
> yes

good to know :-)

> > Silly question - how do I set the disconnect_root? Or is this a
> > not-yet- implemented feature?
> 
> the patches are hanging around I just need to push them out
> 
> > Same question about "disconnected path rules" - IIRC I've never seen
> > them.
> 
> these are still a wip. I am not really a fan othe them but they
> are better than nothing until I can land delegation, and that is
> not something I can see happening this year.

I'd argue that setting disconnect_root should be enough if we recommend 
a path that most probably doesn't exist, like
    disconnect_root /__DISCONNECT_ROOT__/

I'd guess you'll have bigger problems than an accidently too permissive 
profile if this directory really exists ;-)

> > (On a general note, the manpage should only document things that are
> > available to the user. "man crystalball" might be an exception ;-)
> 
> meh, I have pulled out most of the future reference stuff

Thanks!

> > The parser tests also contain mediate_deleted, delegate_deleted,
> > chroot_no_attach and chroot_attach. Some documentation for them
> > would be nice ;-)
> 
> no
> 
> :)
> 
> They are deprecated, and indeed delegate_deleted doesn't even work,
> the less they are documented and the sooner they go away the better.
> I will leave it at that.

But you still want to document the long-gone debug flag? ;-)


> > Besides my comments above - apparmor.d(5) is titled "syntax of
> > security profiles for AppArmor".
> > 
> > All those /sys/module/apparmor details are not really related to
> > that, so maybe they should be in their own manpage?
> > Something like "apparmor.sys"? (better names welcome)
> 
> I am not opposed to moving them into their own man page but I don't
> think having information about debugging/developing a profile is out
> of place here.
> 
> I am going to leave it here for now, but if we get some more info
> together we can look at moving it over.

Agreed, we can split it whenever this section grows ;-)


Regards,

Christian Boltz
-- 
Das ist genauso als ob sich 2 darüber unterhalten, wie man den Indianer
konfiguriert. Und irgendjemand mittendrin den schlauen Rat abläßt, daß
sie doch lieber ein Windoof mit InternetInfectionSystem nehmen sollten.
[Mirco Richter in suse-linux]
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: This is a digitally signed message part.
URL: <https://lists.ubuntu.com/archives/apparmor/attachments/20160609/97728b56/attachment.pgp>