virt-what-cvm.pod

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 virt-what-cvm - detect if we are running in a confidential virtual machine
   6
   7 =head1 SUMMARY
   8
   9 virt-what-cvm [options]
  10
  11 =head1 DESCRIPTION
  12
  13 C<virt-what-cvm> is a tool which can be used to detect if the program
  14 is running in a confidential virtual machine.
  15
  16 The program prints out a list of "facts" about the confidential virtual
  17 machine, derived from heuristics.  One fact is printed per line.
  18
  19 If nothing is printed and the script exits with code 0 (no error),
  20 then it can mean I<either> that the program is running on bare-metal
  21 I<or> the program is running inside a non-confidential virtual machine,
  22 I<or> inside a type of confidential virtual machine which we don't know
  23 about or cannot detect.
  24
  25 =head1 FACTS
  26
  27 =over 4
  28
  29 =item B<amd-sev>
  30
  31 This is a confidential guest running with AMD SEV technology
  32
  33 Status: tested on Fedora 37 QEMU+KVM
  34
  35 =item B<amd-sev-es>
  36
  37 This is a confidential guest running with AMD SEV-ES technology
  38
  39 Status: tested on Fedora 37 QEMU+KVM
  40
  41 =item B<amd-sev-snp>
  42
  43 This is a confidential guest running with AMD SEV-SNP technology
  44
  45 Status: tested on Microsoft Azure SEV-SNP CVM
  46
  47 Status: tested on Fedora 38 QEMU+KVM SEV-SNP (devel snapshot)
  48
  49 =item B<intel-tdx>
  50
  51 This is a confidential guest running with Intel TDX technology
  52
  53 Status: tested on Microsoft Azure TDX CVM (preview)
  54
  55 =item B<hyperv-hcl>
  56
  57 This is a confidential guest running unenlightened under the
  58 HyperV (Azure) HCL (Host Compatibility Layer). This will be
  59 paired with B<amd-sev-snp>.
  60
  61 Status: tested on Microsoft Azure SEV-SNP CVM
  62
  63 =back
  64
  65 =head1 EXIT STATUS
  66
  67 Programs that use or wrap C<virt-what-cvm> should check that the exit
  68 status is 0 before they attempt to parse the output of the command.
  69
  70 A non-zero exit status indicates some error, for example, an
  71 unrecognized command line argument.  If the exit status is non-zero
  72 then the output "facts" (if any were printed) cannot be guaranteed and
  73 should be ignored.
  74
  75 The exit status does I<not> have anything to do with whether the
  76 program is running on baremetal or under confidential virtualization,
  77 nor with whether C<virt-what-cvm> managed detection "correctly" (which
  78 is basically unknowable given the large variety of virtualization
  79 systems out there)
  80
  81 =head1 RUNNING VIRT-WHAT-CVM FROM OTHER PROGRAMS
  82
  83 C<virt-what-cvm> is designed so that you can easily run it from
  84 other programs or wrap it up in a library.
  85
  86 Your program should check the exit status (see the section above).
  87
  88 =head1 IMPORTANT NOTE
  89
  90 This program detects whether it is likely to be running within a known
  91 confidential VM, but does I<NOT> prove that the environment is trustworthy.
  92 To attain trust in the environment requires an attestation report for the
  93 virtual machine, which is then verified by an already trusted 3rd party.
  94
  95 The hardware features that this program relies on to establish facts
  96 about the confidential virtualization environment, are those features
  97 whose behaviour will be proved by verification of an attestation report.
  98
  99 This program I<MAY> have false positives. ie it may report that it is a
 100 confidential VM when it is in fact a non-confidential VM faking it.
 101
 102 This program I<SHOULD NOT> have false negatives. ie it should not fail to
 103 report existance of a confidential VM. Caveat that this only applies to
 104 environments which have been explicitly tested.
 105
 106 If this program does print a fact, this can be used for enabling or
 107 disabling use of certain features, according to whether they are
 108 appropriate for a confidential environment. None the less, the VM
 109 I<MUST NOT> be trusted until an attestation report is verified.
 110
 111 As a protection against false negatives from this tool, environments
 112 requiring high assurance should take one or more of these measures:
 113
 114  * The facts reported by this program I<SHOULD> should be measured
 115    into one of the TPM PCRs
 116  * The attestation report I<SHOULD> cover the facts reported by
 117    this program
 118  * The attestation report I<SHOULD> should cover the enablement
 119    status of any features affected by decisions involving facts
 120    reported by this tool
 121
 122 =head1 SEE ALSO
 123
 124 L<http://people.redhat.com/~rjones/virt-what/>,
 125 L<https://github.com/Azure/confidential-computing-cvm-guest-attestation>,
 126 L<https://virtee.io/>
 127
 128 =head1 AUTHORS
 129
 130 Daniel P. Berrangé <berrange @ redhat . com>
 131
 132 =head1 COPYRIGHT
 133
 134 (C) Copyright 2023 Red Hat Inc.,
 135 L<http://people.redhat.com/~rjones/virt-what/>
 136
 137 This program is free software; you can redistribute it and/or modify
 138 it under the terms of the GNU General Public License as published by
 139 the Free Software Foundation; either version 2 of the License, or
 140 (at your option) any later version.
 141
 142 This program is distributed in the hope that it will be useful,
 143 but WITHOUT ANY WARRANTY; without even the implied warranty of
 144 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 145 GNU General Public License for more details.
 146
 147 You should have received a copy of the GNU General Public License
 148 along with this program; if not, write to the Free Software
 149 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 150
 151 =head1 REPORTING BUGS
 152
 153 Bugs can be viewed on the Red Hat Bugzilla page:
 154 L<https://bugzilla.redhat.com/>.
 155
 156 If you find a bug in virt-what-cvm, please follow these steps to report it:
 157
 158 =over 4
 159
 160 =item 1. Check for existing bug reports
 161
 162 Go to L<https://bugzilla.redhat.com/> and search for similar bugs.
 163 Someone may already have reported the same bug, and they may even
 164 have fixed it.
 165
 166 =item 2. Capture debug and error messages
 167
 168 Run
 169
 170  virt-what-cvm -d > virt-what-cvm.log 2>&1
 171
 172 and keep I<virt-what-cvm.log>.  It may contain error messages which you
 173 should submit with your bug report.
 174
 175 =item 3. Get version of virt-what-cvm.
 176
 177 Run
 178
 179  virt-what-cvm --version
 180
 181 =item 4. Submit a bug report.
 182
 183 Go to L<https://bugzilla.redhat.com/> and enter a new bug.
 184 Please describe the problem in as much detail as possible.
 185
 186 Remember to include the version numbers (step 3) and the debug
 187 messages file (step 2) and as much other detail as possible.
 188
 189 =item 5. Assign the bug to rjones @ redhat.com
 190
 191 Assign or reassign the bug to B<rjones @ redhat.com> (without the
 192 spaces).  You can also send me an email with the bug number if you
 193 want a faster response.
 194
 195 =back