crashpad/tools/mac/exception_port_tool.cc

// Copyright 2014 The Crashpad Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#include <errno.h>
#include <getopt.h>
#include <libgen.h>
#include <mach/mach.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/types.h>
#include <unistd.h>

#include <string>
#include <vector>

#include "base/apple/mach_logging.h"
#include "base/apple/scoped_mach_port.h"
#include "tools/tool_support.h"
#include "util/mach/bootstrap.h"
#include "util/mach/exception_ports.h"
#include "util/mach/mach_extensions.h"
#include "util/mach/symbolic_constants_mach.h"
#include "util/mach/task_for_pid.h"
#include "util/posix/drop_privileges.h"
#include "util/stdlib/string_number_conversion.h"

namespace crashpad {
namespace {

//! \brief Manages a pool of Mach send rights, deallocating all send rights upon
//!     destruction.
//!
//! This class effectively implements what a vector of
//! base::apple::ScopedMachSendRight objects would be.
//!
//! The various “show” operations performed by this program display Mach ports
//! by their names as they are known in this task. For this to be useful, rights
//! to the same ports must have consistent names across successive calls. This
//! cannot be guaranteed if the rights are deallocated as soon as they are used,
//! because if that deallocation causes the task to lose its last right to a
//! port, subsequently regaining a right to the same port would cause it to be
//! known by a new name in this task.
//!
//! Instead of immediately deallocating send rights that are used for display,
//! they can be added to this pool. The pool collects send rights, ensuring that
//! they remain alive in this task, and that subsequent calls that obtain the
//! same rights cause them to be known by the same name. All rights are
//! deallocated upon destruction.
class MachSendRightPool {
 public:
  MachSendRightPool()
      : send_rights_() {
  }

  MachSendRightPool(const MachSendRightPool&) = delete;
  MachSendRightPool& operator=(const MachSendRightPool&) = delete;

  ~MachSendRightPool() {
    for (mach_port_t send_right : send_rights_) {
      kern_return_t kr = mach_port_deallocate(mach_task_self(), send_right);
      MACH_LOG_IF(ERROR, kr != KERN_SUCCESS, kr) << "mach_port_deallocate";
    }
  }

  //! \brief Adds a send right to the pool.
  //!
  //! \param[in] send_right The send right to be added. The pool object takes
  //!     its own reference to the send right, which remains valid until the
  //!     pool object is destroyed. The caller remains responsible for its
  //!     reference to the send right.
  //!
  //! It is possible and in fact likely that one pool will wind up owning the
  //! same send right multiple times. This is acceptable, because send rights
  //! are reference-counted.
  void AddSendRight(mach_port_t send_right) {
    kern_return_t kr = mach_port_mod_refs(mach_task_self(),
                                          send_right,
                                          MACH_PORT_RIGHT_SEND,
                                          1);
    MACH_CHECK(kr == KERN_SUCCESS, kr) << "mach_port_mod_refs";

    send_rights_.push_back(send_right);
  }

 private:
  std::vector<mach_port_t> send_rights_;
};

struct ExceptionHandlerDescription {
  ExceptionPorts::TargetType target_type;
  exception_mask_t mask;
  exception_behavior_t behavior;
  thread_state_flavor_t flavor;
  std::string handler;
};

constexpr char kHandlerNull[] = "NULL";
constexpr char kHandlerBootstrapColon[] = "bootstrap:";

// Populates |description| based on a textual representation in
// |handler_string_ro|, returning true on success and false on failure (parse
// error). The --help string describes the format of |handler_string_ro|.
// Briefly, it is a comma-separated string that allows the members of
// |description| to be specified as "field=value". Values for "target" can be
// "host", "task", or "thread"; values for "handler" are of the form
// "bootstrap:service_name" where service_name will be looked up with the
// bootstrap server; and values for the other fields are interpreted by
// SymbolicConstantsMach.
bool ParseHandlerString(const char* handler_string_ro,
                        ExceptionHandlerDescription* description) {
  static constexpr char kTargetEquals[] = "target=";
  static constexpr char kMaskEquals[] = "mask=";
  static constexpr char kBehaviorEquals[] = "behavior=";
  static constexpr char kFlavorEquals[] = "flavor=";
  static constexpr char kHandlerEquals[] = "handler=";

  std::string handler_string(handler_string_ro);
  char* handler_string_c = &handler_string[0];

  char* token;
  while ((token = strsep(&handler_string_c, ",")) != nullptr) {
    if (strncmp(token, kTargetEquals, strlen(kTargetEquals)) == 0) {
      const char* value = token + strlen(kTargetEquals);
      if (strcmp(value, "host") == 0) {
        description->target_type = ExceptionPorts::kTargetTypeHost;
      } else if (strcmp(value, "task") == 0) {
        description->target_type = ExceptionPorts::kTargetTypeTask;
      } else if (strcmp(value, "thread") == 0) {
        description->target_type = ExceptionPorts::kTargetTypeThread;
      } else {
        return false;
      }
    } else if (strncmp(token, kMaskEquals, strlen(kMaskEquals)) == 0) {
      const char* value = token + strlen(kMaskEquals);
      if (!StringToExceptionMask(
              value,
              kAllowFullName | kAllowShortName | kAllowNumber | kAllowOr,
              &description->mask)) {
        return false;
      }
    } else if (strncmp(token, kBehaviorEquals, strlen(kBehaviorEquals)) == 0) {
      const char* value = token + strlen(kBehaviorEquals);
      if (!StringToExceptionBehavior(
              value,
              kAllowFullName | kAllowShortName | kAllowNumber,
              &description->behavior)) {
        return false;
      }
    } else if (strncmp(token, kFlavorEquals, strlen(kFlavorEquals)) == 0) {
      const char* value = token + strlen(kFlavorEquals);
      if (!StringToThreadStateFlavor(
              value,
              kAllowFullName | kAllowShortName | kAllowNumber,
              &description->flavor)) {
        return false;
      }
    } else if (strncmp(token, kHandlerEquals, strlen(kHandlerEquals)) == 0) {
      const char* value = token + strlen(kHandlerEquals);
      if (strcmp(value, kHandlerNull) != 0 &&
          strncmp(value,
                  kHandlerBootstrapColon,
                  strlen(kHandlerBootstrapColon)) != 0) {
        return false;
      }
      description->handler = std::string(value);
    } else {
      return false;
    }
  }

  return true;
}

// ShowExceptionPorts() shows handlers as numeric mach_port_t values, which are
// opaque and meaningless on their own. ShowBootstrapService() can be used to
// look up a service with the bootstrap server by name and show its mach_port_t
// value, which can then be associated with handlers shown by
// ShowExceptionPorts(). Any send rights obtained by this function are added to
// |mach_send_right_pool|.
void ShowBootstrapService(const std::string& service_name,
                          MachSendRightPool* mach_send_right_pool) {
  base::apple::ScopedMachSendRight service_port(BootstrapLookUp(service_name));
  if (service_port == kMachPortNull) {
    return;
  }

  mach_send_right_pool->AddSendRight(service_port.get());

  printf("service %s %#x\n", service_name.c_str(), service_port.get());
}

// Prints information about all exception ports known for |exception_ports|. If
// |numeric| is true, all information is printed in numeric form, otherwise, it
// will be converted to symbolic constants where possible by
// SymbolicConstantsMach. If |is_new| is true, information will be presented as
// “new exception ports”, indicating that they show the state of the exception
// ports after SetExceptionPort() has been called. Any send rights obtained by
// this function are added to |mach_send_right_pool|.
void ShowExceptionPorts(const ExceptionPorts& exception_ports,
                        bool numeric,
                        bool is_new,
                        MachSendRightPool* mach_send_right_pool) {
  const char* target_name = exception_ports.TargetTypeName();

  ExceptionPorts::ExceptionHandlerVector handlers;
  if (!exception_ports.GetExceptionPorts(ExcMaskValid(), &handlers)) {
    return;
  }

  const char* age_name = is_new ? "new " : "";

  if (handlers.empty()) {
    printf("no %s%s exception ports\n", age_name, target_name);
  }

  for (size_t port_index = 0; port_index < handlers.size(); ++port_index) {
    mach_send_right_pool->AddSendRight(handlers[port_index].port);

    if (numeric) {
      printf(
          "%s%s exception port %zu, mask %#x, port %#x, "
          "behavior %#x, flavor %u\n",
          age_name,
          target_name,
          port_index,
          handlers[port_index].mask,
          handlers[port_index].port,
          handlers[port_index].behavior,
          handlers[port_index].flavor);
    } else {
      std::string mask_string = ExceptionMaskToString(
          handlers[port_index].mask, kUseShortName | kUnknownIsEmpty | kUseOr);
      if (mask_string.empty()) {
        mask_string.assign("?");
      }

      std::string behavior_string = ExceptionBehaviorToString(
          handlers[port_index].behavior, kUseShortName | kUnknownIsEmpty);
      if (behavior_string.empty()) {
        behavior_string.assign("?");
      }

      std::string flavor_string = ThreadStateFlavorToString(
          handlers[port_index].flavor, kUseShortName | kUnknownIsEmpty);
      if (flavor_string.empty()) {
        flavor_string.assign("?");
      }

      printf(
          "%s%s exception port %zu, mask %#x (%s), port %#x, "
          "behavior %#x (%s), flavor %u (%s)\n",
          age_name,
          target_name,
          port_index,
          handlers[port_index].mask,
          mask_string.c_str(),
          handlers[port_index].port,
          handlers[port_index].behavior,
          behavior_string.c_str(),
          handlers[port_index].flavor,
          flavor_string.c_str());
    }
  }
}

// Sets the exception port for |target_port|, a send right to a thread, task, or
// host port, to |description|, which identifies what type of port |target_port|
// is and describes an exception port to be set. Returns true on success.
//
// This function may be called more than once if setting different handlers is
// desired.
bool SetExceptionPort(const ExceptionHandlerDescription* description,
                      mach_port_t target_port) {
  base::apple::ScopedMachSendRight service_port;
  if (description->handler.compare(
          0, strlen(kHandlerBootstrapColon), kHandlerBootstrapColon) == 0) {
    const char* service_name =
        description->handler.c_str() + strlen(kHandlerBootstrapColon);
    service_port = BootstrapLookUp(service_name);
    if (service_port == kMachPortNull) {
      return false;
    }

    // The service port doesn’t need to be added to a MachSendRightPool because
    // it’s not used for display at all. ScopedMachSendRight is sufficient.
  } else if (description->handler != kHandlerNull) {
    return false;
  }

  ExceptionPorts exception_ports(description->target_type, target_port);
  if (!exception_ports.SetExceptionPort(description->mask,
                                        service_port.get(),
                                        description->behavior,
                                        description->flavor)) {
    return false;
  }

  return true;
}

void Usage(const std::string& me) {
  // clang-format off
  fprintf(stderr,
"Usage: %s [OPTION]... [COMMAND [ARG]...]\n"
"View and change Mach exception ports, and run COMMAND if supplied.\n"
"\n"
"  -s, --set-handler=DESCRIPTION  set an exception port to DESCRIPTION, see below\n"
"      --show-bootstrap=SERVICE   look up and display a service registered with\n"
"                                 the bootstrap server\n"
"  -p, --pid=PID                  operate on PID instead of the current task\n"
"  -h, --show-host                display original host exception ports\n"
"  -t, --show-task                display original task exception ports\n"
"      --show-thread              display original thread exception ports\n"
"  -H, --show-new-host            display modified host exception ports\n"
"  -T, --show-new-task            display modified task exception ports\n"
"      --show-new-thread          display modified thread exception ports\n"
"  -n, --numeric                  display values numerically, not symbolically\n"
"      --help                     display this help and exit\n"
"      --version                  output version information and exit\n"
"\n"
"Any operations on host exception ports require superuser permissions.\n"
"\n"
"DESCRIPTION is formatted as a comma-separated sequence of tokens, where each\n"
"token consists of a key and value separated by an equals sign. Available keys:\n"
"  target    which target's exception ports to set: host, task, or thread\n"
"  mask      the mask of exception types to handle: CRASH, ALL, or others\n"
"  behavior  the specific exception handler routine to call: DEFAULT, STATE,\n"
"            or STATE_IDENTITY, possibly with MACH_EXCEPTION_CODES.\n"
"  flavor    the thread state flavor passed to the handler: architecture-specific\n"
"  handler   the exception handler: NULL or bootstrap:SERVICE, indicating that\n"
"            the handler should be looked up with the bootstrap server\n"
"The default DESCRIPTION is\n"
"  target=task,mask=CRASH,behavior=DEFAULT|MACH,flavor=NONE,handler=NULL\n",
          me.c_str());
  // clang-format on
  ToolSupport::UsageTail(me);
}

int ExceptionPortToolMain(int argc, char* argv[]) {
  const std::string me(basename(argv[0]));

  enum ExitCode {
    kExitSuccess = EXIT_SUCCESS,

    // To differentiate this tool’s errors from errors in the programs it execs,
    // use a high exit code for ordinary failures instead of EXIT_FAILURE. This
    // is the same rationale for using the distinct exit codes for exec
    // failures.
    kExitFailure = 125,

    // Like env, use exit code 126 if the program was found but could not be
    // invoked, and 127 if it could not be found.
    // http://pubs.opengroup.org/onlinepubs/9699919799/utilities/env.html
    kExitExecFailure = 126,
    kExitExecENOENT = 127,
  };

  enum OptionFlags {
    // “Short” (single-character) options.
    kOptionSetPort = 's',
    kOptionPid = 'p',
    kOptionShowHost = 'h',
    kOptionShowTask = 't',
    kOptionShowNewHost = 'H',
    kOptionShowNewTask = 'T',
    kOptionNumeric = 'n',

    // Long options without short equivalents.
    kOptionLastChar = 255,
    kOptionShowBootstrap,
    kOptionShowThread,
    kOptionShowNewThread,

    // Standard options.
    kOptionHelp = -2,
    kOptionVersion = -3,
  };

  struct {
    std::vector<const char*> show_bootstrap;
    std::vector<ExceptionHandlerDescription> set_handler;
    pid_t pid;
    task_t alternate_task;
    bool show_host;
    bool show_task;
    bool show_thread;
    bool show_new_host;
    bool show_new_task;
    bool show_new_thread;
    bool numeric;
  } options = {};

  static constexpr option long_options[] = {
      {"set-handler", required_argument, nullptr, kOptionSetPort},
      {"show-bootstrap", required_argument, nullptr, kOptionShowBootstrap},
      {"pid", required_argument, nullptr, kOptionPid},
      {"show-host", no_argument, nullptr, kOptionShowHost},
      {"show-task", no_argument, nullptr, kOptionShowTask},
      {"show-thread", no_argument, nullptr, kOptionShowThread},
      {"show-new-host", no_argument, nullptr, kOptionShowNewHost},
      {"show-new-task", no_argument, nullptr, kOptionShowNewTask},
      {"show-new-thread", no_argument, nullptr, kOptionShowNewThread},
      {"numeric", no_argument, nullptr, kOptionNumeric},
      {"help", no_argument, nullptr, kOptionHelp},
      {"version", no_argument, nullptr, kOptionVersion},
      {nullptr, 0, nullptr, 0},
  };

  int opt;
  while ((opt = getopt_long(argc, argv, "+s:p:htHTn", long_options, nullptr)) !=
         -1) {
    switch (opt) {
      case kOptionSetPort: {
        options.set_handler.push_back({});
        ExceptionHandlerDescription* description = &options.set_handler.back();
        description->target_type = ExceptionPorts::kTargetTypeTask;
        description->mask = EXC_MASK_CRASH;
        description->behavior = EXCEPTION_DEFAULT | MACH_EXCEPTION_CODES;
        description->flavor = THREAD_STATE_NONE;
        description->handler = "NULL";
        if (!ParseHandlerString(optarg, description)) {
          fprintf(stderr,
                  "%s: invalid exception handler: %s\n",
                  me.c_str(),
                  optarg);
          return kExitFailure;
        }
        break;
      }
      case kOptionShowBootstrap:
        options.show_bootstrap.push_back(optarg);
        break;
      case kOptionPid:
        if (!StringToNumber(optarg, &options.pid)) {
          fprintf(stderr, "%s: invalid pid: %s\n", me.c_str(), optarg);
          return kExitFailure;
        }
        break;
      case kOptionShowHost:
        options.show_host = true;
        break;
      case kOptionShowTask:
        options.show_task = true;
        break;
      case kOptionShowThread:
        options.show_thread = true;
        break;
      case kOptionShowNewHost:
        options.show_new_host = true;
        break;
      case kOptionShowNewTask:
        options.show_new_task = true;
        break;
      case kOptionShowNewThread:
        options.show_new_thread = true;
        break;
      case kOptionNumeric:
        options.numeric = true;
        break;
      case kOptionHelp:
        Usage(me);
        return kExitSuccess;
      case kOptionVersion:
        ToolSupport::Version(me);
        return kExitSuccess;
      default:
        ToolSupport::UsageHint(me, nullptr);
        return kExitFailure;
    }
  }
  argc -= optind;
  argv += optind;

  if (options.show_bootstrap.empty() && !options.show_host &&
      !options.show_task && !options.show_thread &&
      options.set_handler.empty() && argc == 0) {
    ToolSupport::UsageHint(me, "nothing to do");
    return kExitFailure;
  }

  base::apple::ScopedMachSendRight alternate_task_owner;
  if (options.pid) {
    if (argc) {
      ToolSupport::UsageHint(me, "cannot combine -p with COMMAND");
      return kExitFailure;
    }

    options.alternate_task = TaskForPID(options.pid);
    if (options.alternate_task == TASK_NULL) {
      return kExitFailure;
    }
    alternate_task_owner.reset(options.alternate_task);
  }

  // This tool may have been installed as a setuid binary so that TaskForPID()
  // could succeed. Drop any privileges now that they’re no longer necessary.
  DropPrivileges();

  MachSendRightPool mach_send_right_pool;

  // Show bootstrap services requested.
  for (const char* service : options.show_bootstrap) {
    ShowBootstrapService(service, &mach_send_right_pool);
  }

  // Show the original exception ports.
  if (options.show_host) {
    ShowExceptionPorts(
        ExceptionPorts(ExceptionPorts::kTargetTypeHost, HOST_NULL),
        options.numeric,
        false,
        &mach_send_right_pool);
  }
  if (options.show_task) {
    ShowExceptionPorts(
        ExceptionPorts(ExceptionPorts::kTargetTypeTask, options.alternate_task),
        options.numeric,
        false,
        &mach_send_right_pool);
  }
  if (options.show_thread) {
    ShowExceptionPorts(
        ExceptionPorts(ExceptionPorts::kTargetTypeThread, THREAD_NULL),
        options.numeric,
        false,
        &mach_send_right_pool);
  }

  if (!options.set_handler.empty()) {
    // Set new exception handlers.
    for (ExceptionHandlerDescription description : options.set_handler) {
      if (!SetExceptionPort(
              &description,
              description.target_type == ExceptionPorts::kTargetTypeTask
                  ? options.alternate_task
                  : TASK_NULL)) {
        return kExitFailure;
      }
    }

    // Show changed exception ports.
    if (options.show_new_host) {
      ShowExceptionPorts(
          ExceptionPorts(ExceptionPorts::kTargetTypeHost, HOST_NULL),
          options.numeric,
          true,
          &mach_send_right_pool);
    }
    if (options.show_new_task) {
      ShowExceptionPorts(
          ExceptionPorts(ExceptionPorts::kTargetTypeTask,
                         options.alternate_task),
          options.numeric,
          true,
          &mach_send_right_pool);
    }
    if (options.show_new_thread) {
      ShowExceptionPorts(
          ExceptionPorts(ExceptionPorts::kTargetTypeThread, THREAD_NULL),
          options.numeric,
          true,
          &mach_send_right_pool);
    }
  }

  if (argc) {
    // Using the remaining arguments, start a new program with the new set of
    // exception ports in effect.
    execvp(argv[0], argv);
    PLOG(ERROR) << "execvp " << argv[0];
    return errno == ENOENT ? kExitExecENOENT : kExitExecFailure;
  }

  return kExitSuccess;
}

}  // namespace
}  // namespace crashpad

int main(int argc, char* argv[]) {
  return crashpad::ExceptionPortToolMain(argc, argv);
}