[Linux] Add kernel.yama.ptrace_scope note when ptrace fails to attach.

[rupprecht]

Summary

A common reason for LLDB failing to attach to an already-running process on Linux is the Yama security module: https://www.kernel.org/doc/Documentation/security/Yama.txt. This patch adds an explaination and suggested fix when it detects that case happening.

This was previously proposed in D106226, but hasn't been updated in a while. The last request was to put the check in a target-specific location, which is the approach this patch takes. I believe Yama only exists on Linux, so it's put in that package.

This has no end-to-end test because I'm not sure how to set ptrace_scope in a test environment -- if there are suggestions on how to do that, I'd be happy to add it. (Also, setting it to 3 is comically irreversible). I tested this locally.

[DavidSpickett]

lldb/unittests/Process/Linux/ProcfsTests.cpp

113

What do you mean by core ids?

[DavidSpickett]

And testing would require the test to sudo ... so I don't think this can be tested.

lldb/source/Plugins/Process/Linux/NativeProcessLinux.cpp

235

Tell me if I understand correctly. This error is only used if you've already failed to attach. So if you had a value of 1 or 2, but attaching worked fine, you wouldn't see this.

Which is why you've said "which can cause" instead of "does cause". As there are some situations with 1 or 2 that do work.

[rupprecht]

• Fix comment typo

lldb/source/Plugins/Process/Linux/NativeProcessLinux.cpp

235

That's exactly right, at least to my understanding.

Level 3 is basically a global kill switch -- no ptrace ever, in any context, even if you're root. The only way to undo that is to reboot, and even then, a hardened machine might set it to 3 in some startup config, so the only way to undo it is remove that setting and *then* reboot.

At level 2 you need CAP_SYS_PTRACE to ptrace an arbitrary process, i.e. you need to be root or have some root-like capability granted. So IIUC, sudo lldb -n blah should still work at that level.

At level 1, ptrace is allowed for anything LLDB launches, as there's a parent-child relationship, but usually not arbitrary other processes. However, an arbitrary process that wants to be debugged could call prctl(PR_SET_PTRACER, PR_SET_PTRACER_ANY, ...) or ptrace(PTRACE_TRACEME, ...), in which case a ptrace on that process should be successful. We could suggest these as other workarounds, but common advice is just to use sudo sysctl -w kernel.yama.ptrace_scope=0, and that's certainly a lot easier to fit into an error message.

Admittedly, using "which can cause" is sort of pedantic -- it can cause ptrace to fail, but there are situations above where it doesn't -- but failing in ptrace with EPERM followed by a non-zero ptrace_scope value is a very strong signal that this *is* the reason. I can't come up with a scenario where it isn't the case, but I this isn't my area of expertise.

The difference between 1 and 2 is subtle enough that I think we can use the same error message in each case, but if we also used it for level 3, that would just frustrate the user who tries to figure out why sudo sysctl -w kernel.yama.ptrace_scope=0 doesn't work. But in general, I'd be happy with whatever wording people would find more useful.

lldb/unittests/Process/Linux/ProcfsTests.cpp

113

Sorry, bad copy/paste from the test above.

[DavidSpickett]

LGTM

lldb/source/Plugins/Process/Linux/NativeProcessLinux.cpp

235

Sounds good to me.

At level 2 you need CAP_SYS_PTRACE to ptrace an arbitrary process

I've had this problem with docker containers started in certain ways, this error message will be really useful there.

lldb/source/Plugins/Process/Linux/NativeProcessLinux.cpp

 #include "lldb/Target/Target.h"
 #include "lldb/Utility/LLDBAssert.h"
 #include "lldb/Utility/LLDBLog.h"
 #include "lldb/Utility/State.h"
 #include "lldb/Utility/Status.h"
 #include "lldb/Utility/StringExtractor.h"
 #include "llvm/ADT/ScopeExit.h"
 #include "llvm/Support/Errno.h"
+#include "llvm/Support/Error.h"
 #include "llvm/Support/FileSystem.h"
 #include "llvm/Support/Threading.h"
 
 #include <linux/unistd.h>
 #include <sys/socket.h>
 #include <sys/syscall.h>
 #include <sys/types.h>
 #include <sys/user.h>
static Status EnsureFDFlags(int fd, int flags) {
   if (fcntl(fd, F_SETFL, status | flags) == -1) {
     error.SetErrorToErrno();
     return error;
   }
 
   return error;
 }
 
+static llvm::Error AddPtraceScopeNote(llvm::Error original_error) {
+  Expected<int> ptrace_scope = GetPtraceScope();
+  if (auto E = ptrace_scope.takeError()) {
+    Log *log = GetLog(POSIXLog::Process);
+    LLDB_LOG(log, "error reading value of ptrace_scope: {0}", E);
+
+    // The original error is probably more interesting than not being able to
+    // read or interpret ptrace_scope.
+    return original_error;
+  }
+
+  // We only have suggestions to provide for 1-3.
+  switch (*ptrace_scope) {
+  case 1:
+  case 2:
+    return llvm::createStringError(
+        std::error_code(errno, std::generic_category()),
+        "The current value of ptrace_scope is %d, which can cause ptrace to "
+        "fail to attach to a running process. To fix this, run:\n"
+        "\tsudo sysctl -w kernel.yama.ptrace_scope=0\n"
+        "For more information, see: "
+        "https://www.kernel.org/doc/Documentation/security/Yama.txt.",
+        *ptrace_scope);
+  case 3:
+    return llvm::createStringError(
+        std::error_code(errno, std::generic_category()),
+        "The current value of ptrace_scope is 3, which will cause ptrace to "
+        "fail to attach to a running process. This value cannot be changed "
+        "without rebooting.\n"
+        "For more information, see: "
+        "https://www.kernel.org/doc/Documentation/security/Yama.txt.");
+  case 0:
+  default:
+    return original_error;
+  }
+}
+
 // Public Static Methods
 
 llvm::Expected<std::unique_ptr<NativeProcessProtocol>>
 NativeProcessLinux::Factory::Launch(ProcessLaunchInfo &launch_info,
                                     NativeDelegate &native_delegate,
                                     MainLoop &mainloop) const {
   Log *log = GetLog(POSIXLog::Process);
 
for (Host::TidMap::iterator it = tids_to_attach.begin();
         // An attach will cause the thread to stop with a SIGSTOP.
         if ((status = PtraceWrapper(PTRACE_ATTACH, tid)).Fail()) {
           // No such thread. The thread may have exited. More error handling
           // may be needed.
           if (status.GetError() == ESRCH) {
             it = tids_to_attach.erase(it);
             continue;
           }
+          if (status.GetError() == EPERM) {
+            // Depending on the value of ptrace_scope, we can return a different
+            // error that suggests how to fix it.
+            return AddPtraceScopeNote(status.ToError());
+          }
           return status.ToError();
         }
 
         int wpid =
             llvm::sys::RetryAfterSignal(-1, ::waitpid, tid, nullptr, __WALL);
         // Need to use __WALL otherwise we receive an error with errno=ECHLD At
         // this point we should have a thread stopped if waitpid succeeds.
         if (wpid < 0) {

lldb/source/Plugins/Process/Linux/Procfs.h

 llvm::Expected<std::vector<lldb::cpu_id_t>>
 GetAvailableLogicalCoreIDs(llvm::StringRef cpuinfo);
 
 /// \return
 ///     A list with all the logical cores available in the system and cache it
 ///     if errors didn't happen.
 llvm::Expected<llvm::ArrayRef<lldb::cpu_id_t>> GetAvailableLogicalCoreIDs();
 
+/// \return
+///     The current value of /proc/sys/kernel/yama/ptrace_scope, parsed as an
+///     integer, or an error if the proc file cannot be read or has non-integer
+///     contents.
+llvm::Expected<int> GetPtraceScope();
+
 } // namespace process_linux
 } // namespace lldb_private

lldb/source/Plugins/Process/Linux/Procfs.cpp

 //===-- Procfs.cpp --------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #include "Procfs.h"
 #include "lldb/Host/linux/Support.h"
+#include "llvm/Support/Error.h"
 #include "llvm/Support/MemoryBuffer.h"
 #include "llvm/Support/Threading.h"
 #include <optional>
 
 using namespace lldb;
 using namespace lldb_private;
 using namespace process_linux;
 using namespace llvm;
Expected<std::vector<cpu_id_t>> cpu_ids = GetAvailableLogicalCoreIDs(
         StringRef(reinterpret_cast<const char *>(cpuinfo->data())));
     if (!cpu_ids)
       return cpu_ids.takeError();
 
     logical_cores_ids.emplace(std::move(*cpu_ids));
   }
   return *logical_cores_ids;
 }
+
+llvm::Expected<int> lldb_private::process_linux::GetPtraceScope() {
+  ErrorOr<std::unique_ptr<MemoryBuffer>> ptrace_scope_file =
+      getProcFile("sys/kernel/yama/ptrace_scope");
+  if (!*ptrace_scope_file)
+    return errorCodeToError(ptrace_scope_file.getError());
+  // The contents should be something like "1\n". Trim it so we get "1".
+  StringRef buffer = (*ptrace_scope_file)->getBuffer().trim();
+  int ptrace_scope_value;
+  if (buffer.getAsInteger(10, ptrace_scope_value)) {
+    return createStringError(inconvertibleErrorCode(),
+                             "Invalid ptrace_scope value: '%s'", buffer.data());
+  }
+  return ptrace_scope_value;
+}

lldb/unittests/Process/Linux/ProcfsTests.cpp

TEST(Perf, RealLogicalCoreIDs) {
   if (!buffer_or_error)
     GTEST_SKIP() << toString(buffer_or_error.takeError());
 
   // At this point we shouldn't fail parsing the core ids
   Expected<ArrayRef<lldb::cpu_id_t>> cpu_ids = GetAvailableLogicalCoreIDs();
   ASSERT_TRUE((bool)cpu_ids);
   ASSERT_GT((int)cpu_ids->size(), 0) << "We must see at least one core";
 }
+
+TEST(Perf, RealPtraceScope) {
+  // We first check we can read /proc/sys/kernel/yama/ptrace_scope
+  auto buffer_or_error =
+      errorOrToExpected(getProcFile("sys/kernel/yama/ptrace_scope"));
+  if (!buffer_or_error)
+    GTEST_SKIP() << toString(buffer_or_error.takeError());
+
+  // At this point we shouldn't fail parsing the ptrace_scope value.
+  Expected<int> ptrace_scope = GetPtraceScope();
+  ASSERT_TRUE((bool)ptrace_scope) << ptrace_scope.takeError();
+  ASSERT_GE(*ptrace_scope, 0)
+      << "Sensible values of ptrace_scope are between 0 and 3";
+  ASSERT_LE(*ptrace_scope, 3)
+      << "Sensible values of ptrace_scope are between 0 and 3";
+}