I think it's great you're working on the documentation; Zope really needs it. The comments below started from Ch 5 of the draft Zope Book, but I think wander into some general issues about the security design, rather than your presentation. It is surprising that users can't change their own password in the default security setup. Or can they, because they "own" themselves? I couldn't quite tell from your description. It would be good to be explicit either way. 1. "Local Managers" I can't understand why you highlight this pattern. It seems useless in real life. In your example, sales managers have no access (as regular employees) to the rest of the site. I can't imagine a real organization which would work that way. Typically you would expect all employees to have certain access rights, and then certain people to manage the content in certain areas. If you can define the same acl_user at two different levels, with different permissions, you need to say that. If you can't, I would just omit this pattern. I think the idea of discussing actual security usage patterns is great, even if I didn't like this specific example. 2. "Trojan Horse attacks" another area I would omit. You do say it's partial protection. However, it's complicated to explain and the payoff is minimal. If someone reads the section quickly and thinks they are safe from such attacks, the section will have done a disservice. The problem is that anyone who can write a page can put a URL or some other item in which runs off to another site (or to the client browser) and does something naughty. The protection is only against executing stuff on the Zope server itself. If you leave the discussion in, try resequencing it. You discuss Trojans in the introductory section of "Ownership and Executable Content" and then seem to drop it, only to have the payoff under "Roles of Executable Objects". It might be worth highlighting the novel feature of this security protection: it is subtractive. In general, Zope seems to add permissions (and other acquirable things) to objects. If you have multiple roles, the permissions add. Proxy roles add. But ownership takes away permissions. 3. Auditing Once things get fairly involved, it would be desirable to have a way of auditing permissions on the site, in the simple sense of printing out all the information needed to tell the security status of objects. Someone is not going to visit each object and check it's permissions. Probably this is a feature the system needs, but if there's a way to do it it would be good to comment on it. I know this is one of the reasons you say to keep it simple. 4. Interference with other systems. The Zope security policy is a lot like permissions in a file system. In fact, Windows 2000 even has acquired security settings (I think called inherited). Windows NT has had the concept of the owner role for awhile. But the Zope security policy is not the same as those other systems, so it will be very easy for people to think it is and get confused. It would be good to warn about this explicitly, perhaps providing a discussion or table of the differences and similarities. 5. I was very curious how security is reflected in objects, in the database, and in the operation of python methods. If you go into programming, it would be good to have something on this. The fact (?) that python code itself does no security checks (if it's in a product) seems worth highlighting. My understanding is that python methods do have some restrictions. Also worth noting. 6. Some comments on the security design. a) The mail example for local roles is a bit worrisome. The method needs one specific permission, but because you have local roles, not local permissions, it gets the manager role, and thus a whole lot of permissions. On its face this is harmless, but handing out more permissions than necessary smells like a potential security hazard. How about having local permissions? b) The additive approach to security is still more of a problem, because it sounds rather easy to give something or someone too much authority, while thinking you have not (as your example about acquiring a permission which had been turned off showed). It also seems likely this differs from the behavior of the seemingly similar systems I mentioned in point 4. c) If my premise in point 1 is correct (local managers not viable for most organizations) it would be good to make it viable. The alternative of adding a bunch of permissions and roles to reflect different organizational units seems likely to become unweildy rather quickly. 7. It would be good to add a discussion of overall site security, particularly the fact that the standard over the web password challenge is fundamentally insecure. That is, the username/password are not themselves sent over a secure connection. Though the password is scrambled, it is done so by a known algorithm. I think the algorithm is invertible, or at least easy to crack. Furthermore, the scrambled password itself would suffice to become that person. To me, this means there's little point in putting a lot of effort into making things secure, because they won't be. And it also implies that actually managing over the web is particularly dangerous, since someone could get manager account access this way.