Draft for review of security for plugin developers

[StackScribe]

This started as the beginnings of a page that summarizes security issues for plugin developers and maintainers. The concept is that this can serve as a checklist and also that other docs (like the Plugin Devloper Tutorial that is under construction) can link to this page to provide current information so we do not have to maintain these links in multiple places.

The general concept is good but this belongs in /doc/developer rather than /doc/book. This PR moves the current content of /doc/developer/security/index.adoc into a separate security-architecture file/page and starts the summary/checklist material (with links) in index.adoc. See discussion below.

This makes this independent of https://github.com/jenkins-infra/jenkins.io/pull/4612.

@daniel-beck @Wadeck @MarkEWaite @dheerajodha

[daniel-beck]

Developer docs are entirely separate (doc/book vs. doc/developer) so probably better to restructure https://www.jenkins.io/doc/developer/security/ to make sense; moving that top-level content to a page "Authentication and Authorization" or so, and then you have a reasonable index page to work with. That's been on my todo list for a while, I've just gotten by directly linking to child pages as needed.

[StackScribe]

@daniel-beck I would be happy to work on https://www.jenkins.io/doc/developer/security/ with you. I think @MarkEWaite and @dheerajodha are going to fix the doc/developer structure so it works like doc/book. So do I understand you to say that you want the current copy of that developer/security section broken up into smaller files with an index.adoc file that is this shorter "checklist" of topics with links to other docs? That would make sense. And then the doc/book/security/index.adoc file could just mention the doc/developer/security section with a link.

Should some of doc/book/security/controller-isolation/required-role-check/ be moved to the doc/developer/security section as well? Or maybe the developer part is already provided in http://localhost:4242/doc/developer/security/remoting-callables/ ? Let's discuss when you have time and then I can implement.

[StackScribe]

I reread the content with Daniel's remarks in my head and I think I understand what he wants so I did it:

• Moved the existing contents of /doc/developer/security/index.adoc into a new security-architecture.adoc file
• Incorporated the content that I had created for /doc/book/security/plugin-developer.adoc into the /doc/developer/security/index.adoc file
• Deleted the /doc/book/security/plugin-developer.adoc file I believe this conforms to the structure that Daniel recommends and it gives us the summary list with links in /doc/developer/security/index.adoc, which really makes more sense.

[daniel-beck]

Should some of doc/book/security/controller-isolation/required-role-check/ be moved to the doc/developer/security section as well? Or maybe the developer part is already provided in http://localhost:4242/doc/developer/security/remoting-callables/ ?

Yes, that should be the separation already; if there's developer content on the admin docs, it should be removed; but all content should be admin suitable.

are going to fix the doc/developer structure so it works like doc/book

Other than the index page, it already does, kinda? Curious to see how that would look though.

And then the doc/book/security/index.adoc file could just mention the doc/developer/security section with a link.

Maybe? Different audiences, so unsure how much of that we need. There are references in the role check doc because it's fairly likely people end up there when things go wrong, so pointing to instructions how to fix (even if implemented by someone else) makes sense IMO.

[StackScribe]

The navigation is different for /dev/developer and /dev/book. Specifically:

• Contents of left frame does not collapse/expand by chapter
• No breadcrumbs accross the top
• Rendered pages do not display subsections in the upper right corner
• Ergo, it's not possible to link to a subsection of a page from another doc None of these are real show-stoppers but I think that fixing them will not be terribly disruptive.

[daniel-beck]

Ergo, it's not possible to link to a subsection of a page from another doc

Most pages on jenkins.io have an 'anchor' link next to each header, it's to the right and appears on hover (unlike GitHub's which is to the left).

Click it and you jump to the anchor. Explicit anchor definitions from Asciidoc also exist, see e.g. https://github.com/jenkins-infra/jenkins.io/blame/d178e145d26822666ff0040c6a451dbdbbcdffdf/content/_data/upgrades/2-303-3.adoc#L3-L4 to get https://www.jenkins.io/doc/upgrade-guide/2.303/#SECURITY-2458

[kwhetstone]

Meg, anything else we need to check for this?

[github-actions[bot]]

Please take a moment and address the merge conflicts of your pull request. Thanks!