Add introductory chapter on Qubes OS security architecture

[GWeck]

No description provided.

[marmarek]

Thanks for producing (generating?) this! Generally looks like a good introduction to Qubes OS, as the first document a user could read.
I have two issues with this page:

• the Qubes OS logo - the image on the page is not that
• duplication with existing documentation - while this doc is a great introduction, it duplicates a lot (most?) of info provided in other sections (especially "Introduction" and "Getting started")

The former is easy to fix. The latter, I'm not sure. If it'd be shorter, I'd say to consider replacing some of the the existing page, but in it's current, longer form it might not be suitable for that (the doc has both generic introduction "why?", but also a bit more detailed "how?"). Images help breaking the "wall of text" impression, but still it's a fairly long doc. Splitting might be an option, but then the doc looses its benefit of being a single document (a single document to describe Qubes OS). Maybe make it explicit that it's an alternative introduction? Or maybe my impression that we need (also) a "short introduction" is wrong and just the long one would be okay? I guess that's up to our documentation maintainers.

This also requires careful review. I've read select parts (probably like 20% of it), and generally looks accurate, but somebody needs to review it in full, especially if it was generated by AI.

[GWeck]

I replaced the AI-generated logo with the official one.

Your other comment is much more difficult to address, and I'm also not sure how to proceed there. Here are some considerations, which may help to find a way:

• The material of this introduction is nothing new, as it was generated from existing texts, but it may help to learn the basic ideas from just one document. Currently, these ideas are distributed over a lot of documentation chapters and even additional texts like the very valuable Joanna's papers. Putting all this together in one place could help readers to understand the basics without needing to search all these locations.

• Compared with the current introduction, this paper is surely quite long. So, possibly, it is not suited for someone who just wishes to get a first impression of what Qubes is at all. It is more valuable for someone willing to spend a bit more time to get a first, deeper understanding. So I added a short paragraph at the beginning telling what to expect from this text. This might help those who open the paper to decide if it is worth for them reading on.

• A short version might also be helpful for those who would not like to spend much time on the subject, but I don't know if this is needed besides the current introduction. I'll have a look into that. Perhaps I can get some ideas.

• Instead of a shorter text for those unwilling to read, it might make sense to use one or more of the images that I put into the forum for discussion.

Regarding the review: I checked the text and images because I don't trust anything generated by AI, but I would be glad for any second opinion from the reviewers. Reading it again and again will, at some time, help nothing anymore, because I just won't recognize the errors.

[GWeck]

Just to clarify for the review process, and in order to be compliant with the "use of AI policy": The material of this pull request was created, at least partially, using the NotebookLM AI tool.

• The texts were based on existing, manually created texts and, in some places, augmented using some output of NotebookLM reports created from the original texts that I wrote. Blending the manually written texts and the AI-generated material required some work and had to be done very carefully, to weed out any AI-generated errors.

• The graphics were created by this tool, using the same original, manually created texts, but reviewed carefully and, in some places, changed manually where they were not correct.

Fortunately, I found not many errors in this process, showing that NotebookLM performs quite well if supplied with a sound basis. In my experience, the results of this way of working were much better than using ChatGPT, which produced mainly crap, and so could not be used for serious work.

[maiska]

Fwiw I think it is superb to talk Qubes OS visually via infographics !!! It could make also a nice introductory presentation! ;)
It is a lot of content and it will take time to discuss all of it and find the perfect place, but I think it is worth it.
At least me will go over your PR @GWeck in the coming I would say weeks :)

[unman]

Thanks for your work on this.
I expect to be able to finalise review by tomorrow.

[unman]

There's something wrong here. What about -
architecture. They may help to provide a starting point to the introductory ...

[unman]

Can you change "traditional OSs" to "a traditional OS"
Under "Specialized tools" can you explicitly say "Use disposable qubes for opening risk files and offline vaults for storing sensitive keys"

In Glance_Qubes_philosophy - what is the purpose of the sub heading?
The term "bulkhead" is introduced - can you find something else?
Under "Anatomy" the information on dom0 is duplicated.
Replace "VMs" with "qubes"
"erasing all traces" is not strictly correct - I dont know whether it's wise to include it.

Glance_Qubes_compartmentalization - There's a large amount of duplication between this and the previous image.
I think the "Digital Compartments" text should be at top of image, with "Color coding" below.
The information on hypervisor type seems to be duplicated, and repeats what appears in a previous image - I think it was not relevant
there. I am not clear it is in the right place here.

Glance_Compartmentalization - I think this is a good image.
It repeats previous information but it seems clear, and has impact.
use "a traditional OS"
I think that "Private keys" is duplicated in the monolith - is this deliberate?
Is the image for impact of web browser in the monolith right? It seems to have a cross in it - could you change this to a poison symbol or death head, which I think you use elsewhere.

I should say that I am not the best person to review this, as is probably obvious.
I will cover the other images later.

[unman]

I am uncertain about the last three images.

[unman]

Glance_Securing_IT - This repeats information provided previously.
There is conflation of proprietary/opensource issues with Qubes approach. There is no reason why Qubes users cannot use proprietary software if they choose.
Here there is also an emphasis on EU providers.
I'm unhappy with the "Expertise Requirement" statement.

Glance_Blueprint - I am unclear how this links with Qubes. Also an emphasis on non-EU dependencies may not sit well with other countries. I think this could be dropped altogether.

Glance_Open_Source_Path - I think that the main image is confusing. Who are these figures chained to the castle? Why is the same building where people are working falling down? Again, I think there is an emphasis on "european", and while I endorse the slide, I am unclear how it provides information on Qubes.

These last slides could be removed without loss to the introduction.If you wanted to show how Qubes could work as a path to digital sovereignty, you could include one slide explicitly referring to that. It would need (I think) not to be state specific.

[GWeck]

There's something wrong here. What about - architecture. They may help to provide a starting point to the introductory ...

Could you explain that? What's wrong?

I made the suggested changes and hope that it's now somewhat clearer. Some of the problems you mentioned are nice examples of AI going wild. I used AI quite heavily to create the pictures, as my drawing abilities are near zero. But in any case, I had to do quite a lot of manual corrections until the output of AI became useful, but I obviously missed some points. So, if only I could draw better, I doubt if the use of AI could then still save work!

Then I removed Glance_Qubes_compartmentalization and the last three pictures. Instead, I added two new pictures on Windows support and a more neutral one on sovereignty.

Thank you for your help!

Just one more point: I see these pictures just as demonstration material that could be used to tell the management what Qubes is, because many managers tend not to be willing or not able to read documentation. So, the really important part of this contribution is, in my opinion, the paper on Qubes security architecture, because that could help to understand the concepts.